diff --git a/documentation/content/en/articles/committers-guide/_index.po b/documentation/content/en/articles/committers-guide/_index.po index e1d331ec20..19fe1141df 100644 --- a/documentation/content/en/articles/committers-guide/_index.po +++ b/documentation/content/en/articles/committers-guide/_index.po @@ -1,8413 +1,8415 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-05-21 14:43-0300\n" +"POT-Creation-Date: 2023-06-19 21:08-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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 <> " "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 <>)." 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:102 msgid "" "man:ssh[1] is required to connect to the project hosts. For more " "information, see <>." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:104 msgid "Useful links:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:106 msgid "link:https://www.FreeBSD.org/internal/[FreeBSD Project Internal Pages]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:107 msgid "link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:108 msgid "" "link:https://www.FreeBSD.org/administration/[FreeBSD Project Administrative " "Groups]" msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:110 #, no-wrap msgid "OpenPGP Keys for FreeBSD" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:115 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 http://en.wikipedia.org/wiki/" "Pretty_Good_Privacy[] for more information." msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:117 #, no-wrap msgid "Creating a Key" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:121 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:123 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:128 msgid "" "Install [.filename]#security/gnupg#. Enter these lines in [.filename]#~/." "gnupg/gpg.conf# to set minimum acceptable defaults:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:139 #, no-wrap msgid "" "fixed-list-mode\n" "keyid-format 0xlong\n" "personal-digest-preferences SHA512 SHA384 SHA256 SHA224\n" "default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed\n" "verify-options show-uid-validity\n" "list-options show-uid-validity\n" "sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g\n" "cert-digest-algo SHA512\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:141 msgid "Generate a key:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:148 #, 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:169 #, 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" " = key expires in n days\n" " w = key expires in n weeks\n" " m = key expires in n months\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:175 #, no-wrap msgid "" "Real name: Chucky Daemon <.>\n" "Email address: notreal@example.com\n" "Comment:\n" "You selected this USER-ID:\n" "\"Chucky Daemon \"\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:178 #, 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:181 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:183 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:185 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:189 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:193 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:195 msgid "" "Committing the new key is shown in <>." msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:197 #, no-wrap msgid "Kerberos and LDAP web Password for FreeBSD Cluster" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:202 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:204 msgid "https://bugs.freebsd.org/bugzilla[Bugzilla]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:205 msgid "https://ci.freebsd.org[Jenkins]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:207 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:211 #, no-wrap msgid "% ssh kpasswd.freebsd.org\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:216 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:219 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:223 #, no-wrap msgid "% kpasswd\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:229 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:232 #, no-wrap msgid "Commit Bit Types" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:238 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:244 #, no-wrap msgid "__Committer Type__" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:245 #, no-wrap msgid "__Responsible__" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:247 #, no-wrap msgid "__Tree Components__" 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 "core@" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:251 #, no-wrap msgid "src/" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:252 #, no-wrap msgid "doc" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:253 #, no-wrap msgid "doceng@" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:255 #, no-wrap msgid "doc/, ports/, src/ documentation" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:256 #, no-wrap msgid "ports" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:257 #, no-wrap msgid "portmgr@" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:258 #, no-wrap msgid "ports/" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:263 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:265 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:266 #, no-wrap msgid "Policy for Committer Activity in Other Trees" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:269 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:270 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:272 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:273 msgid "" "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." msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:275 #, no-wrap msgid "Documentation Implicit (Blanket) Approval" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:279 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:281 msgid "Blanket approval applies to these types of fixes:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:283 msgid "Typos" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:284 msgid "Trivial fixes" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:286 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:289 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:291 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:293 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:294 msgid "Changes in [.filename]#doc/shared/contrib-additional.adoc#" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:296 msgid "" "extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] " "maintenance." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:297 msgid "All link:#commit-steps[Steps for New Committers], doc related" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:298 msgid "Security advisories; Errata Notices; Releases;" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:300 msgid "Used by {security-officer} and {re}." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:301 msgid "Changes in [.filename]#website/content/en/donations/donors.adoc#" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:303 msgid "Used by {donations}." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:305 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:307 #, no-wrap msgid "Git Primer" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:310 #, no-wrap msgid "Git basics" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:317 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:319 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:321 #, no-wrap msgid "Git Mini Primer" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:324 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:325 #, no-wrap msgid "Scope" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:331 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:335 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:337 #, no-wrap msgid "Getting Started For Developers" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:340 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:342 #, no-wrap msgid "Daily use" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:345 msgid "Clone the repository:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:349 #, 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:352 msgid "Then you should have the official mirrors as your remote:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:358 #, 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:361 msgid "Configure the FreeBSD committer data:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:364 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:371 #, 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:374 msgid "Set the push URL:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:378 #, 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:381 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:387 #, 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:390 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:392 msgid "Install commit message template hook:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:397 #, no-wrap msgid "" "% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks\n" "% chmod 755 .git/hooks/prepare-commit-msg\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:400 #, no-wrap msgid "\"admin\" branch" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:403 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:405 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:411 #, 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:413 msgid "Alternatively, you can add a worktree for the `admin` branch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:417 #, 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:421 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:423 msgid "For pushing, either specify the full refspec:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:427 #, no-wrap msgid "git push freebsd HEAD:refs/internal/admin\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:429 #, no-wrap msgid "Keeping Current With The FreeBSD src Tree" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:436 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:437 #, no-wrap msgid "Branch Names" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:439 msgid "FreeBSD-CURRENT uses the `main` branch." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:441 msgid "`main` is the default branch." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:443 msgid "For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:445 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:447 msgid "https://www.freebsd.org/releng/[] shows:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:449 msgid "`main` and `stable/⋯` branches open" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:450 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:452 msgid "Examples:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:454 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:455 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:456 #, no-wrap msgid "Repositories" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:459 msgid "" "Please see the <> 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:462 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:463 #, no-wrap msgid "Deep Clone" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:467 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:470 #, no-wrap msgid "% git clone -o freebsd $URL -b branch []\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:475 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 `` 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:480 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:481 #, no-wrap msgid "Shallow Clone" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:487 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:491 #, 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:496 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:501 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:503 #, no-wrap msgid "Building" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:507 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:514 #, 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:516 msgid "so that won't be covered in depth here." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:519 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:520 #, no-wrap msgid "Updating" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:524 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:527 #, no-wrap msgid "% git pull --ff-only\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:532 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:535 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:536 #, no-wrap msgid "Selecting a Specific Version" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:540 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:542 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:545 #, no-wrap msgid "% git checkout 08b8197a74\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:548 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:551 #, no-wrap msgid "Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:555 #, 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:558 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:560 #: documentation/content/en/articles/committers-guide/_index.adoc:1668 #, no-wrap msgid " git checkout -b \n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:562 #, 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:566 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:567 #, no-wrap msgid "Bisecting" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:571 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:576 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:583 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:587 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:592 #, 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:596 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 " "5rf0bd68) and good would be a8163e165. 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:600 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:607 #, 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:616 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:618 #, no-wrap msgid "Signing the commits, tags, and pushes, with GnuPG" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:623 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:625 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:627 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:630 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:637 #, 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:645 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:651 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:653 #, no-wrap msgid "Verifying signatures" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:656 msgid "" "Commit signatures can be verified by running either `git verify-commit " "`, or `git log --show-signature`." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:658 msgid "" "Tag signatures can be verified with `git verity-tag `, or `git tag " "-v `." 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:667 #, no-wrap msgid "Ports Considerations" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:670 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:673 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:677 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:679 #, no-wrap msgid "Commit message formats" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:683 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:685 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:688 #, no-wrap msgid "category/port: Summary.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:690 #, no-wrap msgid "Description of why the changes where made.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:692 #, no-wrap msgid "PR:\t 12345\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/articles/committers-guide/_index.adoc:698 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:700 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:702 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:704 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:706 #, no-wrap msgid "Managing Local Changes" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:709 msgid "" "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)." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:715 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:716 #, no-wrap msgid "Keeping local changes" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:723 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:727 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:728 #, no-wrap msgid "Keeping a local branch" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:735 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:739 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:741 msgid "====== Create a branch" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:746 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:768 #, 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 \n" " #include \n" " #include \n" "+#undef COLORLS\n" " #ifdef COLORLS\n" " #include \n" " #include \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:775 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:777 msgid "====== Time to update" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:782 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:788 #, 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:793 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:795 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:802 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 more " "complete treatment can be found at the end of this section." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:805 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:815 #, 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 \", 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:818 msgid "" "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):" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:827 #, no-wrap msgid "" " <<<<<<< HEAD\n" " #ifdef COLORLS_NEW\n" " #include \n" " =======\n" " #undef COLORLS\n" " #ifdef COLORLS\n" " #include \n" " >>>>>>> 646e0f9cda11... no color ls\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:831 #, no-wrap msgid "" "The new code is first, and your code is second.\n" "The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:835 msgid "#undef COLORLS_NEW #ifdef COLORLS_NEW #include " msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:839 #, no-wrap msgid "" "save the file.\n" "The rebase was interrupted, so you have to complete it:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:842 msgid "% git add ls.c % git rebase --continue" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:847 #, no-wrap msgid "" "which tells Git that ls.c has been fixed and to continue the rebase operation.\n" "Since there was a conflict, you will get kicked into the editor to update the commit message if necessary.\n" "If the commit message is still accurate, just exit the editor.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:852 #, no-wrap msgid "" "If you get stuck during the rebase, do not panic.\n" "git rebase --abort will take you back to a clean slate.\n" "It is important, though, to start with an unmodified tree.\n" "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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:855 #, no-wrap 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.\n" "It is a good resource for issues that arise occasionally but are too obscure for this guide.\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:856 #, no-wrap msgid "Switching to a Different FreeBSD Branch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:860 msgid "" "If you wish to shift from stable/12 to the current branch. If you have a " "deep clone, the following will suffice: [source,shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:863 msgid "% git checkout main % # build and install here..." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:869 #, no-wrap msgid "" "If you have a local branch, though, there are one or two caveats.\n" "First, rebase will rewrite history, so you will likely want to do something to save it.\n" "Second, jumping branches tends to cause more conflicts.\n" "If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:873 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:880 #, no-wrap msgid "" "What the above does is checkout no-color-ls.\n" "Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it.\n" "Then you rebase onto the `main` branch.\n" "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\n" "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).\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:882 #, no-wrap msgid "[[mfc-with-git]]\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:882 #, no-wrap msgid "MFC (Merge From Current) Procedures" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:883 #, no-wrap msgid "Summary" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:887 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:888 #, no-wrap msgid "Single commit MFC" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:891 #: documentation/content/en/articles/committers-guide/_index.adoc:931 #: documentation/content/en/articles/committers-guide/_index.adoc:967 #: documentation/content/en/articles/committers-guide/_index.adoc:1083 #: documentation/content/en/articles/committers-guide/_index.adoc:1096 #: documentation/content/en/articles/committers-guide/_index.adoc:1123 #: documentation/content/en/articles/committers-guide/_index.adoc:1135 #: documentation/content/en/articles/committers-guide/_index.adoc:1201 #: documentation/content/en/articles/committers-guide/_index.adoc:1219 #: documentation/content/en/articles/committers-guide/_index.adoc:1241 #: documentation/content/en/articles/committers-guide/_index.adoc:1259 #: documentation/content/en/articles/committers-guide/_index.adoc:1279 #: documentation/content/en/articles/committers-guide/_index.adoc:1294 #: documentation/content/en/articles/committers-guide/_index.adoc:1313 #: documentation/content/en/articles/committers-guide/_index.adoc:1345 #: documentation/content/en/articles/committers-guide/_index.adoc:1392 #: documentation/content/en/articles/committers-guide/_index.adoc:1456 msgid "[source,shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:894 msgid "% git checkout stable/X % git cherry-pick -x $HASH --edit" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:898 #, no-wrap msgid "" "For MFC commits, for example a vendor import, you would need to specify one parent for cherry-pick purposes.\n" "Normally, that would be the \"first parent\" of the branch you are cherry-picking from, so:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:900 #: documentation/content/en/articles/committers-guide/_index.adoc:921 #: documentation/content/en/articles/committers-guide/_index.adoc:944 #: documentation/content/en/articles/committers-guide/_index.adoc:955 #: documentation/content/en/articles/committers-guide/_index.adoc:1173 #: documentation/content/en/articles/committers-guide/_index.adoc:1267 #: documentation/content/en/articles/committers-guide/_index.adoc:1352 #: documentation/content/en/articles/committers-guide/_index.adoc:1364 #: documentation/content/en/articles/committers-guide/_index.adoc:1376 #: documentation/content/en/articles/committers-guide/_index.adoc:1402 #: documentation/content/en/articles/committers-guide/_index.adoc:1414 #: documentation/content/en/articles/committers-guide/_index.adoc:1421 #: documentation/content/en/articles/committers-guide/_index.adoc:1463 #: documentation/content/en/articles/committers-guide/_index.adoc:1497 #: documentation/content/en/articles/committers-guide/_index.adoc:1504 #: documentation/content/en/articles/committers-guide/_index.adoc:1513 #: documentation/content/en/articles/committers-guide/_index.adoc:1542 #: documentation/content/en/articles/committers-guide/_index.adoc:1558 #: documentation/content/en/articles/committers-guide/_index.adoc:1591 #: documentation/content/en/articles/committers-guide/_index.adoc:1612 #: documentation/content/en/articles/committers-guide/_index.adoc:1643 #: documentation/content/en/articles/committers-guide/_index.adoc:1655 #: documentation/content/en/articles/committers-guide/_index.adoc:1686 #: documentation/content/en/articles/committers-guide/_index.adoc:1695 #: documentation/content/en/articles/committers-guide/_index.adoc:1705 #: documentation/content/en/articles/committers-guide/_index.adoc:1721 #: documentation/content/en/articles/committers-guide/_index.adoc:1737 #: documentation/content/en/articles/committers-guide/_index.adoc:1748 #: documentation/content/en/articles/committers-guide/_index.adoc:1755 #: documentation/content/en/articles/committers-guide/_index.adoc:1768 #: documentation/content/en/articles/committers-guide/_index.adoc:1788 #: documentation/content/en/articles/committers-guide/_index.adoc:1802 #: documentation/content/en/articles/committers-guide/_index.adoc:1818 #: documentation/content/en/articles/committers-guide/_index.adoc:1830 #: documentation/content/en/articles/committers-guide/_index.adoc:1849 #: documentation/content/en/articles/committers-guide/_index.adoc:1860 #: documentation/content/en/articles/committers-guide/_index.adoc:1870 #: documentation/content/en/articles/committers-guide/_index.adoc:1908 #: documentation/content/en/articles/committers-guide/_index.adoc:1916 #: documentation/content/en/articles/committers-guide/_index.adoc:1927 #: documentation/content/en/articles/committers-guide/_index.adoc:1948 #: documentation/content/en/articles/committers-guide/_index.adoc:2008 #, no-wrap msgid "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:903 msgid "% git checkout stable/X % git cherry-pick -x $HASH -m 1 --edit" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:906 #, no-wrap 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`.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:909 #, no-wrap msgid "" "Once the cherry-pick is finished, push with `git push`.\n" "If you get an error due to losing the commit race, use `git pull --rebase` and try to push again.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:910 #, no-wrap msgid "MFC to RELENG branch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:914 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:919 #, no-wrap msgid "" "* Merge or direct commit to the appropriate `stable/X` branch first before merging to the `releng/X.Y` branch.\n" "* Use the hash that's in the `stable/X` branch for the MFC to `releng/X.Y` branch.\n" "* Leave both \"cherry picked from\" lines in the commit message.\n" "* Be sure to add the `Approved by:` line when you are in the editor.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:924 msgid "% git checkout releng/13.0 % git cherry-pick -x $HASH --edit" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:927 #, no-wrap 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.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:928 #, no-wrap msgid "Multiple commit MFC" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:939 msgid "" "% git checkout -b tmp-branch stable/X % for h in $HASH_LIST; do git cherry-" "pick -x $h; done % git rebase -i stable/X # mark each of the commits after " "the first as 'squash' # Update the commit message to reflect all elements of " "commit, if necessary. # Be sure to retain the \"cherry picked from\" " "lines. % git push freebsd HEAD:stable/X" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:942 #, no-wrap msgid "If the push fails due to losing the commit race, rebase and try again:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:950 msgid "" "% git checkout stable/X % git pull % git checkout tmp-branch % git rebase " "stable/X % git push freebsd HEAD:stable/X" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:953 #, no-wrap msgid "Once the MFC is complete, you can delete the temporary branch:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:958 msgid "% git checkout stable/X % git branch -d tmp-branch" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:960 #, no-wrap msgid "MFC a vendor import" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:965 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:969 msgid "% git cherry-pick -x -m 1 $HASH" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:972 #, no-wrap msgid "" "is typically what you want.\n" "This will tell cherry-pick to apply the correct diff.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:977 #, no-wrap msgid "" "There are some, hopefully, rare cases where it's possible that the `main` branch was merged backwards by the conversion script.\n" "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.\n" "Just do:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:980 msgid "% git cherry-pick --abort % git cherry-pick -x -m 2 $HASH" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:982 #, no-wrap msgid "to do that. The `--abort` will cleanup the failed first attempt.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:983 #, no-wrap msgid "Redoing a MFC" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:988 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: [source,shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:990 msgid "% git reset --hard freebsd/stable/12" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:993 #, no-wrap msgid "" "though if you have some revs you want to keep, and others you don't,\n" "using `git rebase -i` is better.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:994 #, no-wrap msgid "Considerations when MFCing" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:997 msgid "" "When committing source commits to stable and releng branches, we have the " "following goals:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1001 #, no-wrap msgid "" "* Clearly mark direct commits distinct from commits that land a change from another branch.\n" "* Avoid introducing known breakage into stable and releng branches.\n" "* Allow developers to determine which changes have or have not been landed from one branch to another.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1003 #, no-wrap msgid "With Subversion, we used the following practices to achieve these goals:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1007 #, no-wrap msgid "" "* Using `MFC` and `MFS` tags to mark commits that merged changes from another branch.\n" "* Squashing fixup commits into the main commit when merging a change.\n" "* Recording mergeinfo so that `svn mergeinfo --show-revs` worked.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1011 #, no-wrap msgid "" "With Git, we will need to use different strategies to achieve the same goals.\n" "This document aims to define best practices when merging source commits using Git that achieve these goals.\n" "In general, we aim to use Git's native support to achieve these goals rather than enforcing practices built on Subversion's model.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1014 #, no-wrap 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.\n" "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`.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1015 #, no-wrap msgid "Finding Eligible Hashes to MFC" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1021 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:1022 #, no-wrap msgid "Commit message standards" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1023 #, no-wrap msgid "Marking MFCs" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1026 msgid "The project has adopted the following practice for marking MFCs:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1028 #, no-wrap 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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1030 #, no-wrap msgid "When merging multiple commits, keep all the \"cherry picked from\" lines.\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1031 #, no-wrap msgid "Trim Metadata?" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1035 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1044 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1048 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1051 msgid "" "Preserving existing metadata provides a very simple workflow. Developers " "use `git cherry-pick -x` without having to edit the log message." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1054 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1056 msgid "" "The bottom line is that developers will likely need to curate their commit " "message for MFCs that are non-trivial." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1058 msgid "[[vendor-import-git]]" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:1058 #, no-wrap msgid "Vendor Imports with Git" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1061 msgid "This section describes the vendor import procedure with Git in detail." msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1062 #, no-wrap msgid "Branch naming convention" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1065 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:1071 msgid "" "[NOTE] ==== 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1074 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:1075 #, no-wrap msgid "Updating an old vendor import" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1081 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1085 msgid "% git worktree add ../mtree vendor/NetBSD/mtree" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1087 #, no-wrap msgid "Update the Sources in the Vendor Branch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1090 msgid "" "Prepare a full, clean tree of the vendor sources. Import everything but " "merge only what is needed." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1094 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1108 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1112 #, no-wrap msgid "" "Note: I run the `git diff` and `git status` commands to make sure nothing weird was present.\n" "Also I used `-m` to illustrate, but you should compose a proper message in an editor (using a commit message template).\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1117 #, no-wrap msgid "" "It is also important to create an annotated tag using `git tag -a`, otherwise the push will be rejected.\n" "Only annotated tags are allowed to be pushed.\n" "The annotated tag gives you a chance to enter a commit message.\n" "Enter the version you are importing, along with any salient new features or fixes in that version.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1118 #, no-wrap msgid "Updating the FreeBSD Copy" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1121 msgid "At this point you can push the import to `vendor` into our repo." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1125 msgid "% git push --follow-tags freebsd vendor/NetBSD/mtree" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1128 #, no-wrap msgid "`--follow-tags` tells `git push` to also push tags associated with the locally committed revision.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1129 #, no-wrap msgid "Updating the FreeBSD source tree" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1133 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:1138 msgid "% cd ../src % git subtree merge -P contrib/mtree vendor/NetBSD/mtree" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1143 #, no-wrap msgid "" "This would generate a subtree merge commit of `contrib/mtree` against the local `vendor/NetBSD/mtree` branch.\n" "If there were conflicts, you would need to fix them before committing.\n" "Include details about the changes being merged in the merge commit message.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1144 #, no-wrap msgid "Rebasing your change against latest FreeBSD source tree" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1147 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1150 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1152 msgid "" "The following steps should be taken to easily recreate the merge commit as " "if `git rebase --merge-commits` worked properly:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1169 #, no-wrap msgid "" "* cd to the top of the repo\n" "* Create a side branch `XXX` with the **contents** of the merged tree.\n" "* Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch.\n" "** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare.\n" "** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed)\n" "* checkout `main`\n" "* create a branch `YYY` (allows for easier unwinding if things go wrong)\n" "* Re-do the subtree merge\n" "* Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it.\n" "** The trailing `.` is important, as is being at the top level of the repo.\n" "** Rather than switching branches to XXX, it splats the contents of XXX on top of the repo\n" "* Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch).\n" "* Make sure the branches are the same.\n" "* Do whatever review you need, including having others check it out if you think that's needed.\n" "* Push the commit, if you 'lost the race' again, just redo these steps again (see below for a recipe)\n" "* Delete the branches once the commit is upstream. They are throw-a-way.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1171 #, no-wrap 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):\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1184 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1188 #, no-wrap 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:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1190 msgid "" "% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if " "starting over is just going to be easier" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1192 #, no-wrap msgid "Pushing the changes" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1197 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1199 msgid "" "After review, when you are sure it is a good change, you can push it to the " "FreeBSD repo:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1205 msgid "" "% git push freebsd YYY:main\t# put the commit on upstream's 'main' branch % " "git branch -D XXX\t\t# Throw away the throw-a-way branches. % git branch -D " "YYY" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1212 #, no-wrap msgid "" "Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine.\n" "If you use such names for other work, then you'll need to pick different names, or risk losing the other work.\n" "There is nothing magic about these names.\n" "Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above.\n" "Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1213 #, no-wrap msgid "How to redo things if need be" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1217 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1226 msgid "" "% git checkout -B XXX YYY\t# recreate that throw-away-branch XXX and switch " "to it % git merge freebsd/main\t# 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 .\t\t# XXX branch has the conflict resolution % git " "commit -c XXX~1\t\t# -c reuses the commit message from commit before rebase" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1229 #, no-wrap msgid "Then go check it out as above and push as above when ready.\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:1230 #, no-wrap msgid "Creating a new vendor branch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1237 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:1238 #, no-wrap msgid "Create the repo" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1247 msgid "" "% cd /some/where % mkdir glorbnitz % cd glorbnitz % git init % git checkout -" "b vendor/glorbnitz" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1250 #, no-wrap msgid "At this point, you have a new repo, where all new commits will go on the `vendor/glorbnitz` branch.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1252 #, no-wrap 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.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1253 #, no-wrap msgid "Copy the sources in" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1257 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1262 msgid "% cp -r ~/glorbnitz/* . % git add *" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1265 #, no-wrap msgid "At this point, you should have a pristine copy of glorbnitz ready to commit.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1269 msgid "% git commit -m \"Import GlorbNitz frobnosticator revision 3.1415\"" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1273 #, no-wrap 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.\n" "Not everybody will know so, for your actual commit, you should follow the <> section instead of emulating the brief style used here.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1274 #, no-wrap msgid "Now import it into our repository" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1277 msgid "Now you need to import the branch into our repository." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1283 msgid "" "% cd /path/to/freebsd/repo/src % git remote add glorbnitz /some/where/" "glorbnitz % git fetch glorbnitz vendor/glorbnitz" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1288 #, no-wrap msgid "" "Note the vendor/glorbnitz branch is in the repo. At this point the `/some/where/glorbnitz` can be deleted, if you like.\n" "It was only a means to an end.\n" "// perhaps the real treasure was the friends it made along the way...\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1289 #, no-wrap msgid "Tag and push" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1292 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1300 msgid "" "% git worktree add ../glorbnitz vendor/glorbnitz % cd ../glorbnitz % git tag " "--annotate vendor/glorbnitz/3.1415 # Make sure the commit is good with \"git " "show\" % git push --follow-tags freebsd vendor/glorbnitz" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1303 #, no-wrap msgid "By 'good' we mean:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1309 #, no-wrap msgid "" ". All the right files are present\n" ". None of the wrong files are present\n" ". The vendor branch points at something sensible\n" ". The tag looks good, and is annotated\n" ". The commit message for the tag has a quick summary of what's new since the last tag\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1310 #, no-wrap msgid "Time to finally merge it into the base tree" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1319 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1322 #, no-wrap msgid "Here 'good' means:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1327 #, no-wrap msgid "" ". All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.\n" ". No other changes are in the tree.\n" ". The commit messages look <>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.\n" ". UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1333 #, no-wrap msgid "" "[NOTE]\n" "====\n" "This hasn't connected `glorbnitz` to the build yet.\n" "How so do that is specific to the software being imported and is beyond the scope of this tutorial.\n" "====\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1334 #, no-wrap msgid "Keeping current" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1340 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1343 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1347 msgid "% git config --global pull.ff only" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1350 #, no-wrap msgid "You may need to omit the --global if you want this setting to apply to only this repository.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1356 msgid "% cd freebsd-src % git checkout main % git pull (--ff-only|--rebase)" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1360 #, no-wrap 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.\n" "This can be harder to recover from.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1362 #, no-wrap msgid "The longer form is also recommended.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1369 msgid "" "% cd freebsd-src % git checkout main % git fetch freebsd % git merge --ff-" "only freebsd/main" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1374 #, no-wrap msgid "" "These commands reset your tree to the `main` branch, and then update it from where you pulled the tree from originally.\n" "It's important to switch to `main` before doing this so it moves forward.\n" "Now, it's time to move the changes forward:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1378 msgid "% git rebase -i main working" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1385 #, no-wrap msgid "" "This will bring up an interactive screen to change the defaults.\n" "For now, just exit the editor.\n" "Everything should just apply.\n" "If not, then you'll need to resolve the diffs.\n" "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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1387 #, no-wrap msgid "[[git-push-upstream]]\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1387 #, no-wrap msgid "Time to push changes upstream" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1390 msgid "" "First, ensure that the push URL is properly configured for the upstream " "repository." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1394 msgid "" "% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1398 #, no-wrap msgid "" "Then, verify that user name and email are configured right.\n" "We require that they exactly match the passwd entry in FreeBSD cluster.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1400 #, no-wrap msgid "Use\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1404 msgid "freefall% gen-gitconfig.sh" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1407 #, no-wrap msgid "on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1412 #, no-wrap msgid "" "The below command merges the `working` branch into the upstream `main` branch.\n" "It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.\n" "This syntax pushes the `working` branch to `main`, moving the `main` branch forward.\n" "You will only be able to do this if this results in a linear change to `main` (e.g. no merges).\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1416 msgid "% git push freebsd working:main" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1419 #, no-wrap msgid "If your push is rejected due to losing a commit race, rebase your branch before trying again:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1426 msgid "" "% git checkout working % git fetch freebsd % git rebase freebsd/main % git " "push freebsd working:main" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1429 #, no-wrap msgid "[[git-push-upstream-alt]]\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1429 #, no-wrap msgid "Time to push changes upstream (alternative)" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1435 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: [source,shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1439 msgid "% git checkout main % git merge --ff-only `working` % git push freebsd" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1443 #, no-wrap msgid "" "If you lose the race, then try again with\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1446 msgid "% git pull --rebase % git push freebsd" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1449 #, no-wrap 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.\n" "Note: merging vendor branch commits will not work with this technique.\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1450 #, no-wrap msgid "Finding the Subversion Revision" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1454 msgid "" "You'll need to make sure that you've fetched the notes (see the <> for details). Once you have these, notes will show up in the " "git log command like so:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1458 msgid "% git log" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1461 #, no-wrap msgid "If you have a specific version in mind, you can use this construct:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1465 msgid "% git log --grep revision=XXXX" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1469 #, no-wrap msgid "" "to find the specific revision.\n" "The hex number after 'commit' is the hash you can use to refer to this commit.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1471 #, no-wrap msgid "[[git-faq]]\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:1471 #, no-wrap msgid "Git FAQ" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1474 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:1480 msgid "" "[NOTE] ==== 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:1481 #, no-wrap msgid "Users" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1483 #, no-wrap msgid "How do I track -current and -stable with only one copy of the repository?" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1488 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1492 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1495 #, no-wrap msgid "" "First, you need to clone the FreeBSD repository, shown here cloning into `freebsd-current` to reduce confusion.\n" "$URL is whatever mirror works best for you:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1499 msgid "" "% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/" "notes/*' $URL freebsd-current" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1502 #, no-wrap msgid "then once that's cloned, you can simply create a worktree from it:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1507 msgid "% cd freebsd-current % git worktree add ../freebsd-stable-12 stable/12" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1511 #, no-wrap msgid "" "this will checkout `stable/12` into a directory named `freebsd-stable-12` that's a peer to the `freebsd-current` directory.\n" "Once created, it's updated very similarly to how you might expect:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1521 msgid "" "% cd freebsd-current % git checkout main % git pull --ff-only # changes from " "upstream now local and current tree updated % cd ../freebsd-stable-12 % git " "merge --ff-only freebsd/stable/12 # now your stable/12 is up to date too" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1524 #, no-wrap 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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1526 #, no-wrap msgid "Here's https://adventurist.me/posts/00296[a good writeup] that goes into more detail.\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1527 #, no-wrap msgid "Developers" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1529 #, no-wrap msgid "Ooops! I committed to `main`, instead of another branch." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1532 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1534 #, no-wrap msgid "**A:** First, don't panic.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1538 #, no-wrap msgid "" "Second, don't push.\n" "In fact, you can fix almost anything if you haven't pushed.\n" "All the answers in this section assume no push has happened.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1540 #, no-wrap msgid "The following answer assumes you committed to `main` and want to create a branch called `issue`:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1546 #, no-wrap msgid "" "% git branch issue # Create the 'issue' branch\n" "% git reset --hard freebsd/main # Reset 'main' back to the official tip\n" "% git checkout issue # Back to where you were\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1548 #, no-wrap msgid "Ooops! I committed something to the wrong branch!" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1552 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1556 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1564 msgid "" "# We're on branch wilma % git checkout fred\t\t# move to fred branch % git " "cherry-pick wilma\t\t# copy the misplaced commit % git checkout wilma\t\t# " "go back to wilma branch % git reset --hard HEAD^\t# move what wilma refers " "to back 1 commit" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1568 #, no-wrap msgid "" "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\n" "cherry-pick it over.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1570 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1576 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1578 #, no-wrap msgid "**Q:** I want to split off some changes from branch `wilma` into branch `fred`\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1584 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1589 #, no-wrap 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.\n" "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.\n" "Some people would create a tag/branch called `pre-split` before starting in case something goes wrong in the split.\n" "You can undo it with the following sequence:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1596 msgid "" "% git checkout pre-split\t# Go back % git branch -D fred\t\t# delete the " "fred branch % git checkout -B wilma\t\t# reset the wilma branch % git branch " "-d pre-split\t# Pretend it didn't happen" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1600 #, no-wrap msgid "" "The last step is optional.\n" "If you are going to try again to split, you'd omit it.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1604 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1606 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1610 #, no-wrap 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.\n" "Nothing weird happened when I did that, but let's say it did.\n" "The way to look at what you've done is with the `git reflog`:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1625 msgid "" "% git reflog 6ff9c25 (HEAD -> wilma) HEAD@{0}: rebase -i (finish): returning " "to refs/heads/wilma 6ff9c25 (HEAD -> wilma) HEAD@{1}: rebase -i (start): " "checkout main 869cbd3 HEAD@{2}: rebase -i (start): checkout wilma a6a5094 " "(fred) HEAD@{3}: rebase -i (finish): returning to refs/heads/fred a6a5094 " "(fred) HEAD@{4}: rebase -i (pick): Encourage contributions 1ccd109 (freebsd/" "main, main) HEAD@{5}: rebase -i (start): checkout main 869cbd3 HEAD@{6}: " "rebase -i (start): checkout fred 869cbd3 HEAD@{7}: checkout: moving from " "wilma to fred 869cbd3 HEAD@{8}: commit: Encourage contributions ... %" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1633 #, no-wrap msgid "" "Here we see the changes I've made.\n" "You can use it to figure out where things went wrong.\n" "I'll just point out a few things here.\n" "The first one is that HEAD@{X} is a 'commitish' thing, so you can use that as an argument to a command.\n" "Although if that command commits anything to the repository, the X numbers change.\n" "You can also use the hash (first column).\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1641 #, no-wrap msgid "" "Next, 'Encourage contributions' was the last commit I made to `wilma` before I decided to split things up.\n" "You can also see the same hash is there when I created the `fred` branch to do that.\n" "I started by rebasing `fred` and you see the 'start', each step, and the 'finish' for that process.\n" "While we don't need it here, you can figure out exactly what happened.\n" "Fortunately, to fix this, you can follow the prior answer's steps, but with the hash `869cbd3` instead of `pre-split`.\n" "While that seems a bit verbose, it's easy to remember since you're doing one thing at a time.\n" "You can also stack:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1646 msgid "% git checkout -B wilma 869cbd3 % git branch -D fred" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1653 #, no-wrap msgid "" "and you are ready to try again.\n" "The `checkout -B` with the hash combines checking out and creating a branch for it.\n" "The `-B` instead of `-b` forces the movement of a pre-existing branch.\n" "Either way works, which is what's great (and awful) about Git.\n" "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:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1659 msgid "% git checkout 869cbd3 M\tfaq.md Note: checking out '869cbd3'." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1663 msgid "" "You are in 'detached HEAD' state. You can look around, make experimental " "changes and commit them, and you can discard any commits you make in this " "state without impacting any branches by performing another checkout." msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1666 msgid "" "If you want to create a new branch to retain commits you create, you may do " "so (now or later) by using -b with the checkout command again. Example:" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1671 msgid "HEAD is now at 869cbd3 Encourage contributions % git checkout -B wilma" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1674 #, no-wrap 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.\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1675 #, no-wrap msgid "Ooops! I did a `git pull` and it created a merge commit, what do I do?" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1679 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1681 #, no-wrap msgid "**A:** This can happen when you invoke the pull with your development branch checked out.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1684 #, no-wrap msgid "" "Right after the pull, you will have the new merge commit checked out.\n" "Git supports a `HEAD^#` syntax to examine the parents of a merge commit:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1689 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1693 #, no-wrap msgid "" "From those logs, you can easily identify which commit is your development work.\n" "Then you simply reset your branch to the corresponding `HEAD^#`:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1697 msgid "git reset --hard HEAD^2" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1700 #, no-wrap msgid "**Q:** But I also need to fix my `main` branch. How do I do that?\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1703 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1707 msgid "git branch -f main freebsd/main" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1712 #, no-wrap msgid "" "There's nothing magical about branches in Git: they are just labels on a graph that are automatically moved forward by making commits.\n" "So the above works because you're just moving a label.\n" "There's no metadata about the branch that needs to be preserved due to this.\n" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:1713 #, no-wrap msgid "Mixing and matching branches" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1717 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1719 #, no-wrap msgid "**A:** This is a job for cherry pick.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1725 msgid "" "% git checkout worker % git checkout -b feature\t# create a new branch % git " "cherry-pick main..async\t# bring in the changes" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1730 #, no-wrap msgid "" "You now have a new branch called `feature`.\n" "This branch combines commits from both branches.\n" "You can further curate it with `git rebase`.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1732 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1735 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1741 msgid "" "% git checkout driver\t\t# Checkout the driver % git checkout -b kernel\t# " "Create kernel branch % git checkout -b userland\t# Create userland branch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1746 #, no-wrap msgid "" "Now you have two identical branches.\n" "So, it's time to separate out the commits.\n" "We'll assume first that all the commits in `driver` go into either the `kernel` or the `userland` branch, but not both.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1750 msgid "% git rebase -i main kernel" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1753 #, no-wrap 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).\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1757 msgid "% git rebase -i main userland" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1760 #, no-wrap msgid "and do the same thing you did with the `kernel` branch.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1763 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1766 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1772 msgid "% git checkout kernel % git log driver % git cherry-pick $HASH" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1778 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1781 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1786 #, no-wrap msgid "" "So let's assume that there's just one commit with a clean tree.\n" "You can either use `git rebase` with an `edit` line, or you can use this with the commit on the tip.\n" "The steps are the same either way.\n" "The first thing we need to do is to back up one commit while leaving the changes uncommitted in the tree:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1790 msgid "% git reset HEAD^" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1793 #, no-wrap msgid "Note: Do not, repeat do not, add `--hard` here since that also removes the changes from your tree.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1797 #, no-wrap msgid "" "Now, if you are lucky, the change needing to be split up falls entirely along file lines.\n" "In that case you can just do the usual `git add` for the files in each group than do a `git commit`.\n" "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).\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1800 #, no-wrap msgid "" "If you are not lucky, you'll need to split apart files.\n" "There's another tool to do that which you can apply one file at a time.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1804 msgid "git add -i foo/bar.c" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1810 #, no-wrap msgid "" "will step through the diffs, prompting you, one at time, whether to include or exclude the hunk.\n" "Once you're done, `git commit` and you'll have the remainder in your tree.\n" "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\n" "and use the `git rebase -i` to fold the related commits together).\n" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:1811 #, no-wrap msgid "Cloning and Mirroring" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1814 #, no-wrap msgid "**Q:** I'd like to mirror the entire Git repository, how do I do that?\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1816 #, no-wrap msgid "**A:** If all you want to do is mirror, then\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1820 msgid "% git clone --mirror $URL" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1824 #, no-wrap msgid "" "will do the trick.\n" "However, there are two disadvantages to this if you want to use it for anything other than a mirror you'll reclone.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1828 #, no-wrap msgid "" "First, this is a 'bare repository' which has the repository database, but no checked out worktree.\n" "This is great for mirroring, but terrible for day to day work.\n" "There's a number of ways around this with `git worktree`:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1836 msgid "" "% git clone --mirror https://git.freebsd.org/ports.git ports.git % cd ports." "git % git worktree add ../ports main % git worktree add ../quarterly " "branches/2020Q4 % cd ../ports" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1839 #, no-wrap msgid "But if you aren't using your mirror for further local clones, then it's a poor match.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1842 #, no-wrap 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.\n" "This means that you'll lose changes if you are committing to this repository on anything other than private project branches.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1844 #, no-wrap msgid "**Q:** So what can I do instead?\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1847 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1851 #, no-wrap msgid " fetch = +refs/heads/*:refs/remotes/freebsd/*\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1854 #, no-wrap msgid "which says just fetch the branch refs.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1858 #, no-wrap msgid "" "However, the FreeBSD repository has a number of other things in it.\n" "To see those, you can add explicit refspecs for each ref namespace, or you can fetch everything.\n" "To setup your repository to do that:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1862 msgid "git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1866 #, no-wrap msgid "" "which will put everything in the upstream repository into your local repository's `refs/freebsd/` namespace.\n" "Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1868 #, no-wrap msgid "You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces.\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1872 msgid "git log refs/freebsd/vendor/zlib/1.2.10" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1875 #, no-wrap msgid "would look at the log for the vendor branch for zlib starting at 1.2.10.\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:1876 #, no-wrap msgid "Collaborating with others" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1880 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1882 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1884 msgid "" "Before you begin, make sure that your local Git repo is up to date and has " "the correct origins set <>" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1891 msgid "" "[source,shell] ```` % git remote -v freebsd https://git.freebsd.org/src.git " "(fetch) freebsd ssh://git@gitrepo.freebsd.org/src.git (push) ````" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1894 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1897 msgid "" "Now add a remote on your local system that points to your fork: [source," "shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1904 msgid "" "% git remote add github git@github.com:gvnn3/freebsd-src.git % git remote -v " "github\tgit@github.com:gvnn3/freebsd-src.git (fetch) github\tgit@github.com:" "gvnn3/freebsd-src.git (push) freebsd\thttps://git.freebsd.org/src.git " "(fetch) freebsd\tssh://git@gitrepo.freebsd.org/src.git (push)" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1906 #, no-wrap msgid "With this in place you can create a branch <>\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1910 msgid "% git checkout -b gnn-pr2001-fix" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1914 #, no-wrap 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.\n" "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:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1920 msgid "" "% git push github fatal: The current branch gnn-pr2001-fix has no upstream " "branch. To push the current branch and set the remote as upstream, use" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1922 #, no-wrap msgid " git push --set-upstream github gnn-pr2001-fix\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1925 #, no-wrap msgid "Setting the push as +git+ advises allows it to succeed:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1941 #, 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" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1943 #, no-wrap msgid "" "[new branch] gnn-feature -> gnn-feature\n" "Branch 'gnn-feature' set up to track remote branch 'gnn-feature' from 'github'.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1946 #, no-wrap msgid "Subsequent changes to the same branch will push correctly by default:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1959 #, 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1963 #, no-wrap msgid "" "At this point your work is now in your branch on +GitHub+ and you can\n" "share the link with other collaborators.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1965 #, no-wrap msgid "[[github-pull-land]]\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:1965 #, no-wrap msgid "Landing a github pull request" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1970 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:1974 msgid "" "Before beginning, make sure that the local Git repo is up to date and has " "the correct origins set <> In addition, " "make sure to have the following origins: [source,shell]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:1980 msgid "" "% git remote -v freebsd https://git.freebsd.org/src.git (fetch) freebsd " "ssh://git@gitrepo.freebsd.org/src.git (push) github https://github.com/" "freebsd/freebsd-src (fetch) github https://github.com/freebsd/freebsd-src " "(fetch)" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2000 #, no-wrap msgid "" "Often pull requests are simple: requests that contain only a single commit.\n" "In this case, a streamlined approach may be used, though the approach in the prior section will also work.\n" "Here, a branch is created, the change is cherry picked, the commit message adjusted, and sanity-checked before being pushed.\n" "The branch `staging` is used in this example but it can be any name.\n" "This technique works for any number of commits in the pull request, especially when the changes apply cleanly to the FreeBSD tree.\n" "However, when there's multiple commits, especially when minor adjustments are needed, `git rebase -i` works better than `git cherry-pick`.\n" "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`.\n" "The PR number is `$PR` below.\n" "When adjusting the message, add `Pull Request: https://github.com/freebsd-src/pull/$PR`.\n" "All pull requests committed to the FreeBSD repository should be reviewed by at least one person.\n" "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.\n" "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.\n" "Add anybody that reviews and approves the commit on github to `Reviewed by:` as well.\n" "As always, care should be taken to ensure the change does what it is supposed to, and that no malicious code is present.\n" "[NOTE]\n" "======\n" "In addition, please check to make sure that the pull request author name is not anonymous.\n" "Github's web editing interface generates names like:\n" "[source,shell]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2002 #, no-wrap msgid "Author: github-user <38923459+github-user@users.noreply.github.com>\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2006 #, no-wrap msgid "" "A polite request to the author for a better name and/or email should be made.\n" "Extra care should be taken to ensure no style issue or malicious code is introduced.\n" "======\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2018 msgid "" "% git fetch github pull/$PR/head:staging % git rebase -i main staging\t# to " "move the staging branch forward, adjust commit message here % git checkout main % git pull --ff-only\t\t# to get the " "latest if time has passed % git checkout main % git merge --ff-only staging " " % git push freebsd --push-option=confirm-author" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2023 #, no-wrap msgid "" "[.procedure]\n" "====\n" "For complicated pull requests that have multiple commits with conflicts, follow the following outline.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2031 #, no-wrap msgid "" ". checkout the pull request `git checkout github/pull/XXX`\n" ". create a branch to rebase `git checkout -b staging`\n" ". rebase the `staging` branch to the latest `main` with `git rebase -i main staging`\n" ". resolve conflicts and do whatever testing is needed\n" ". fast forward the `staging` branch into `main` as above\n" ". final sanity check of changes to make sure all is well\n" ". push to FreeBSD's Git repository.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2036 #, no-wrap msgid "" "This will also work when bringing branches developed elsewhere into the local tree for committing.\n" "====\n" "Once finished with the pull request, close it using GitHub's web interface.\n" "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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2038 #, no-wrap msgid "[[vcs-history]]\n" msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:2038 #, no-wrap msgid "Version Control History" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2041 msgid "The project has moved to <>." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2047 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2053 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2059 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2061 msgid "[[conventions]]" msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:2061 #, no-wrap msgid "Setup, Conventions, and Traditions" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2066 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2068 msgid "[[conventions-committers]]" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2068 #, no-wrap msgid "For New Committers" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2071 msgid "" "Those who have been given commit rights to the FreeBSD repositories must " "follow these steps." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2074 #, no-wrap msgid "" "* Get mentor approval before committing each of these changes!\n" "* 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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2079 #, no-wrap msgid "" "[[commit-steps]]\n" "[.procedure]\n" "====\n" "*Steps for New Committers*\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2126 #, no-wrap msgid "" ". Add an Author Entity\n" "+\n" "[.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.\n" ". Update the List of Developers and Contributors\n" "+\n" "[.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.\n" "+\n" "[.filename]#doc/shared/contrib-additional.adoc# - _Remove_ the entry. Entries are sorted by first name.\n" ". Add a News Item\n" "+\n" "[.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.\n" ". Add a PGP Key\n" "+\n" "`{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.\n" "+\n" "Use [.filename]#doc/documentation/tools/checkkey.sh# to verify that keys meet minimal best-practices standards.\n" "+\n" "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.\n" "+\n" "[NOTE]\n" "======\n" "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].\n" "======\n" ". Update Mentor and Mentee Information\n" "+\n" "[.filename]#src/share/misc/committers-.dot# - Add an entry to the current committers section, where _repository_ is `doc`, `ports`, or `src`, depending on the commit privileges granted.\n" "+\n" "Add an entry for each additional mentor/mentee relationship in the bottom section.\n" ". Generate a Kerberos Password\n" "+\n" "See <> 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).\n" ". Optional: Enable Wiki Account\n" "+\n" "link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas.\n" "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.\n" "Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account.\n" ". Optional: Update Wiki Information\n" "+\n" "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.\n" ". Optional: Update Ports with Personal Information\n" "+\n" "[.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.\n" ". Optional: Prevent Duplicate Mailings\n" "+\n" "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.\n" "====\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2128 #, no-wrap msgid "[[conventions-everyone]]\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2128 #, no-wrap msgid "For Everyone" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2148 msgid "" "[[conventions-everyone-steps]] [.procedure] ==== . 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! . 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. + [NOTE] ====== If " "your e-mail system uses SPF with strict rules, you should exclude `mx2." "FreeBSD.org` from SPF checks. ====== + Due to the severe load dealing with " "SPAM places on the central mail servers that do the mailing list processing, " "the front-end server does do some basic checks and will drop some messages " "based on these checks. At the moment proper DNS information for the " "connecting host is the only check in place but that may change. Some people " "blame these checks for bouncing valid email. To have these checks turned off " "for your email, create a file named [.filename]#~/.spam_lover# on `freefall." "FreeBSD.org`. + [NOTE] ====== 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: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2150 msgid "[[smtp-setup]]" msgstr "" #. type: Title ==== #: documentation/content/en/articles/committers-guide/_index.adoc:2150 #, no-wrap msgid "SMTP Access Setup" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2153 msgid "" "For those willing to send e-mail messages through the FreeBSD.org " "infrastructure, follow the instructions below:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2174 msgid "" "[.procedure] ==== . 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 <>). The " "`_yourusername_/mail` principal is preferred, as it is only valid for " "authenticating to mail resources. + [NOTE] ====== Do not include `@FreeBSD." "org` when entering in your username. ====== + .Additional Notes [NOTE] " "====== * Will only accept mail from `_yourusername_@FreeBSD.org`. If you are " "authenticated as one user, you are not permitted to send mail from another. " "* A header will be appended with the SASL username: (`Authenticated sender: " "_username_`). * Host has various rate limits in place to cut down on brute " "force attempts. ====== ====" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2176 msgid "[[smtp-setup-local-mta]]" msgstr "" #. type: Title ===== #: documentation/content/en/articles/committers-guide/_index.adoc:2176 #, 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:2179 msgid "" "It is also possible to use a local MTA to forward locally sent emails to the " "FreeBSD.org SMTP servers." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2184 msgid "[[smtp-setup-local-postfix]] .Using Postfix [example] ====" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2186 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:2188 msgid "[.programlisting]" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2194 msgid "" "sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps " "smtp_sasl_auth_enable = yes smtp_sasl_security_options = noanonymous " "smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd " "smtp_use_tls = yes" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2197 #, no-wrap msgid "Create [.filename]#/usr/local/etc/postfix/relayhost_maps# with the following content:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2199 #: documentation/content/en/articles/committers-guide/_index.adoc:2206 #: documentation/content/en/articles/committers-guide/_index.adoc:2213 #: documentation/content/en/articles/committers-guide/_index.adoc:2221 #: documentation/content/en/articles/committers-guide/_index.adoc:2236 #: documentation/content/en/articles/committers-guide/_index.adoc:2246 #: documentation/content/en/articles/committers-guide/_index.adoc:2260 #: documentation/content/en/articles/committers-guide/_index.adoc:2290 #, no-wrap msgid "[.programlisting]\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2201 msgid "yourusername@FreeBSD.org [smtp.freebsd.org]:587" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2204 #, no-wrap msgid "Create [.filename]#/usr/local/etc/postfix/sasl_passwd# with the following content:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2208 #, no-wrap msgid "[smtp.freebsd.org]:587 yourusername:yourpassword\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2211 #, no-wrap 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#:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2216 msgid "" "smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps " "smtpd_sender_restrictions = reject_known_sender_login_mismatch" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2219 #, no-wrap msgid "Create [.filename]#/usr/local/etc/postfix/sender_login_maps# with the following content:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2223 msgid "yourusername@FreeBSD.org yourlocalusername" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2227 #, no-wrap msgid "" "Where _yourlocalusername_ is the SASL username used to connect to the local instance of Postfix.\n" "====\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2232 #, no-wrap msgid "" "[[smtp-setup-local-opensmtpd]]\n" ".Using OpenSMTPD\n" "[example]\n" "====\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2234 #, no-wrap 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#:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2239 msgid "" "action \"freebsd\" relay host smtp+tls://freebsd@smtp.freebsd.org:587 auth " " match from any auth yourlocalusername mail-from " "\"_yourusername_@freebsd.org\" for any action \"freebsd\"" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2242 #, no-wrap msgid "Where _yourlocalusername_ is the SASL username used to connect to the local instance of OpenSMTPD.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2244 #, no-wrap msgid "Create [.filename]#/usr/local/etc/mail/secrets# with the following content:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2248 msgid "freebsd\tyourusername:yourpassword" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2255 #, no-wrap msgid "" "====\n" "[[smtp-setup-local-exim]]\n" ".Using Exim\n" "[example]\n" "====\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2258 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2267 #, 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: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2279 #, no-wrap msgid "" "Transport Section:\n" "freebsd_smtp:\n" " driver = smtp\n" " tls_certificate=\n" " tls_privatekey=\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 = \n" " dkim_selector = \n" " dkim_private_key= \n" " dnssec_request_domains = *\n" " hosts_require_auth = smtp.freebsd.org\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2285 #, no-wrap msgid "" "Authenticators:\n" "fixed_plain:\n" " driver = plaintext\n" " public_name = PLAIN\n" " client_send = ^example/mail^examplePassword\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2288 #, no-wrap msgid "Create [.filename]#/usr/local/etc/exim/freebsd_send# with the following content:\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/committers-guide/_index.adoc:2292 msgid "example@freebsd.org:smtp.freebsd.org::587" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2295 #, no-wrap msgid "====\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2297 #, no-wrap msgid "[[mentors]]\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2297 #, no-wrap msgid "Mentors" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2302 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:2305 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:2309 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 <>." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2311 msgid "[[pre-commit-review]]" msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:2311 #, no-wrap msgid "Pre-Commit Review" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2316 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:2322 #, no-wrap msgid "" "* All non-trivial changes should be reviewed before they are committed to the repository.\n" "* Reviews may be conducted by email, in Bugzilla, in Phabricator, or by another mechanism. Where possible, reviews should be public.\n" "* The developer responsible for a code change is also responsible for making all necessary review-related changes.\n" "* 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.\n" "* Timeouts are not a substitute for review.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2324 #, no-wrap 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:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2331 #, no-wrap 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.\n" "* 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.\n" "* Ask for help on mailing lists, IRC, etc. Others may be able to either help you directly, or suggest a reviewer.\n" "* 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.\n" "+\n" "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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2336 #, no-wrap msgid "" "Developers should participate in code reviews as both reviewers and reviewees.\n" "If someone is kind enough to review your code, you should return the favor for someone else.\n" "Note that while anyone is welcome to review and give feedback on a patch, only an appropriate subject-matter expert can approve a change.\n" "This will usually be a committer who works with the code in question on a regular basis.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2339 #, no-wrap msgid "" "In some cases, no subject-matter expert may be available.\n" "In those cases, a review by an experienced developer is sufficient when coupled with appropriate testing.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2341 #, no-wrap msgid "[[commit-log-message]]\n" msgstr "" #. type: Title == #: documentation/content/en/articles/committers-guide/_index.adoc:2341 #, no-wrap msgid "Commit Log Messages" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2344 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:2345 #, no-wrap msgid "Why are commit messages important?" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2349 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:2352 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:2355 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:2357 msgid "Commit messages serve at least three purposes:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2364 #, no-wrap msgid "" "* Communicating with other developers\n" "+\n" "FreeBSD commits generate email to various mailing lists.\n" "These include the commit message along with a copy of the patch itself.\n" "Commit messages are also viewed through commands like git log.\n" "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.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2370 #, no-wrap msgid "" "* Making Changes Discoverable\n" "+\n" "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.\n" "Verbose, detailed commit messages allow searches for changes that might be relevant.\n" "For example, `git log --since 1year --grep 'USB timeout'`.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2376 #, no-wrap msgid "" "* Providing historical documentation\n" "+\n" "Commit messages serve to document changes for future developers, perhaps years or decades later.\n" "This future developer may even be you, the original author.\n" "A change that seems obvious today may be decidedly not so much later on.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2378 #, no-wrap msgid "The `git blame` command annotates each line of a source file with the change (hash and subject line) that brought it in.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2380 #, no-wrap msgid "Having established the importance, here are elements of a good FreeBSD commit message:\n" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2381 #, no-wrap msgid "Start with a subject line" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2385 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:2386 #, no-wrap msgid "Keep subject lines short" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2391 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 63 characters, and " "aim for about 50 or fewer if possible." msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2392 #, 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:2395 msgid "" "If the change relates to a specific component the subject line may be " "prefixed with that component name and a colon (:)." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2397 msgid "✓ `foo: Add -k option to keep temporary data`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2399 msgid "" "Include the prefix in the 63-character limit suggested above, so that `git " "log --oneline` avoids wrapping." msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2400 #, no-wrap msgid "Capitalize the first letter of the subject" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2404 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:2405 #, no-wrap msgid "Do not end the subject line with punctuation" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2409 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:2410 #, 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:2413 msgid "Separate the body from the subject with a blank line." msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2415 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:2417 msgid "✓ `ls: Fix typo in usage text`" msgstr "" #. type: Title === #: documentation/content/en/articles/committers-guide/_index.adoc:2418 #, no-wrap msgid "Limit messages to 72 columns" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2424 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:2425 #, no-wrap msgid "Use the present tense, imperative mood" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2430 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:2435 #, 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:2436 #, no-wrap msgid "Focus on what and why, not how" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2439 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:2443 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:2445 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:2446 #, 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:2449 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:2450 #, no-wrap msgid "Write commit messages for your future self" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2454 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:2455 #, no-wrap msgid "Commit messages should stand alone" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2459 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:2463 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:2464 #, no-wrap msgid "Include appropriate metadata in a footer" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/committers-guide/_index.adoc:2467 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:2469 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:2471 msgid "The key words or phrases are:" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:2476 #, no-wrap msgid "" "[.informaltable]\n" "[cols=\"20%,80%\", frame=\"none\"]" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:2477 #, no-wrap msgid "`PR:`" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:2479 #, 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:2480 #, no-wrap msgid "`Reported by:`" msgstr "" #. type: Table #: documentation/content/en/articles/committers-guide/_index.adoc:2484 #, 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:2485 +#: documentation/content/en/articles/committers-guide/_index.adoc:2486 #, no-wrap -msgid "`Submitted by:`" +msgid "" +"`Submitted by:` +\n" +"(deprecated)" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2487 +#: documentation/content/en/articles/committers-guide/_index.adoc:2488 #, 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:2488 +#: documentation/content/en/articles/committers-guide/_index.adoc:2489 #, no-wrap msgid "`Reviewed by:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2503 +#: documentation/content/en/articles/committers-guide/_index.adoc:2504 #, 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 (maintainer)\n" "...." msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2504 +#: documentation/content/en/articles/committers-guide/_index.adoc:2505 #, no-wrap msgid "`Tested by:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2506 +#: documentation/content/en/articles/committers-guide/_index.adoc:2507 #, 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:2507 +#: documentation/content/en/articles/committers-guide/_index.adoc:2508 #, no-wrap msgid "`Approved by:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2532 +#: documentation/content/en/articles/committers-guide/_index.adoc:2533 #, 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" "\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:2533 +#: documentation/content/en/articles/committers-guide/_index.adoc:2534 #, no-wrap msgid "`Obtained from:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2535 +#: documentation/content/en/articles/committers-guide/_index.adoc:2536 #, 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:2536 +#: documentation/content/en/articles/committers-guide/_index.adoc:2537 #, no-wrap msgid "`Fixes:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2538 +#: documentation/content/en/articles/committers-guide/_index.adoc:2539 #, 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 --oneline GIT-COMMIT-HASH`." msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2539 +#: documentation/content/en/articles/committers-guide/_index.adoc:2540 #, no-wrap msgid "`MFC after:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2541 +#: documentation/content/en/articles/committers-guide/_index.adoc:2542 #, 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:2542 +#: documentation/content/en/articles/committers-guide/_index.adoc:2543 #, no-wrap msgid "`MFC to:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2544 +#: documentation/content/en/articles/committers-guide/_index.adoc:2545 #, 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:2545 +#: documentation/content/en/articles/committers-guide/_index.adoc:2546 #, no-wrap msgid "`MFH:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2547 +#: documentation/content/en/articles/committers-guide/_index.adoc:2548 #, 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:2548 +#: documentation/content/en/articles/committers-guide/_index.adoc:2549 #, no-wrap msgid "`Relnotes:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2550 +#: documentation/content/en/articles/committers-guide/_index.adoc:2551 #, 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:2551 +#: documentation/content/en/articles/committers-guide/_index.adoc:2552 #, no-wrap msgid "`Security:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2553 +#: documentation/content/en/articles/committers-guide/_index.adoc:2554 #, 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:2554 +#: documentation/content/en/articles/committers-guide/_index.adoc:2555 #, no-wrap msgid "`Event:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2556 +#: documentation/content/en/articles/committers-guide/_index.adoc:2557 #, 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:2557 +#: documentation/content/en/articles/committers-guide/_index.adoc:2558 #, no-wrap msgid "`Sponsored by:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2559 +#: documentation/content/en/articles/committers-guide/_index.adoc:2560 #, 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:2560 +#: documentation/content/en/articles/committers-guide/_index.adoc:2561 #, no-wrap msgid "`Pull Request:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2564 +#: documentation/content/en/articles/committers-guide/_index.adoc:2565 #, 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:2565 +#: documentation/content/en/articles/committers-guide/_index.adoc:2566 #, no-wrap msgid "`Signed-off-by:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2567 +#: documentation/content/en/articles/committers-guide/_index.adoc:2568 #, no-wrap msgid "ID certifies compliance with https://developercertificate.org/" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2568 +#: documentation/content/en/articles/committers-guide/_index.adoc:2569 #, no-wrap msgid "`Differential Revision:`" msgstr "" #. type: Table -#: documentation/content/en/articles/committers-guide/_index.adoc:2570 +#: documentation/content/en/articles/committers-guide/_index.adoc:2571 #, 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:2572 +#: documentation/content/en/articles/committers-guide/_index.adoc:2573 #, 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:2578 +#: documentation/content/en/articles/committers-guide/_index.adoc:2579 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:2582 -#: documentation/content/en/articles/committers-guide/_index.adoc:2600 -#: documentation/content/en/articles/committers-guide/_index.adoc:2615 -#: documentation/content/en/articles/committers-guide/_index.adoc:2631 -#: documentation/content/en/articles/committers-guide/_index.adoc:2646 +#: documentation/content/en/articles/committers-guide/_index.adoc:2583 +#: documentation/content/en/articles/committers-guide/_index.adoc:2601 +#: documentation/content/en/articles/committers-guide/_index.adoc:2616 +#: documentation/content/en/articles/committers-guide/_index.adoc:2632 +#: documentation/content/en/articles/committers-guide/_index.adoc:2647 #, no-wrap msgid "...\n" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2584 +#: documentation/content/en/articles/committers-guide/_index.adoc:2585 #, no-wrap msgid "PR:\t\t12345\n" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2587 +#: documentation/content/en/articles/committers-guide/_index.adoc:2588 msgid "" "The committer sets the author of the patch with `git commit --author \"John " "Smith \"`." msgstr "" #. type: Block title -#: documentation/content/en/articles/committers-guide/_index.adoc:2590 +#: documentation/content/en/articles/committers-guide/_index.adoc:2591 #, no-wrap msgid "Commit Log for a Commit Needing Review" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2596 +#: documentation/content/en/articles/committers-guide/_index.adoc:2597 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:2602 +#: documentation/content/en/articles/committers-guide/_index.adoc:2603 #, no-wrap msgid "Reviewed by:\t-arch\n" msgstr "" #. type: Block title -#: documentation/content/en/articles/committers-guide/_index.adoc:2606 +#: documentation/content/en/articles/committers-guide/_index.adoc:2607 #, no-wrap msgid "Commit Log for a Commit Needing Approval" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2611 +#: documentation/content/en/articles/committers-guide/_index.adoc:2612 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:2617 +#: documentation/content/en/articles/committers-guide/_index.adoc:2618 #, no-wrap msgid "Approved by:\tabc (maintainer)\n" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2620 +#: documentation/content/en/articles/committers-guide/_index.adoc:2621 msgid "Where _abc_ is the account name of the person who approved." msgstr "" #. type: Block title -#: documentation/content/en/articles/committers-guide/_index.adoc:2622 +#: documentation/content/en/articles/committers-guide/_index.adoc:2623 #, 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:2627 +#: documentation/content/en/articles/committers-guide/_index.adoc:2628 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:2633 +#: documentation/content/en/articles/committers-guide/_index.adoc:2634 #, no-wrap msgid "Obtained from:\tOpenBSD\n" msgstr "" #. type: Block title -#: documentation/content/en/articles/committers-guide/_index.adoc:2637 +#: documentation/content/en/articles/committers-guide/_index.adoc:2638 #, 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:2642 +#: documentation/content/en/articles/committers-guide/_index.adoc:2643 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:2648 +#: documentation/content/en/articles/committers-guide/_index.adoc:2649 #, no-wrap msgid "MFC after:\t2 weeks\n" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2651 +#: documentation/content/en/articles/committers-guide/_index.adoc:2652 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:2654 +#: documentation/content/en/articles/committers-guide/_index.adoc:2655 msgid "It is often necessary to combine these." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2658 +#: documentation/content/en/articles/committers-guide/_index.adoc:2659 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:2660 +#: documentation/content/en/articles/committers-guide/_index.adoc:2661 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:2661 +#: documentation/content/en/articles/committers-guide/_index.adoc:2662 #, no-wrap msgid "Example Combined Commit Log" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2672 +#: documentation/content/en/articles/committers-guide/_index.adoc:2673 #, 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:2677 +#: documentation/content/en/articles/committers-guide/_index.adoc:2678 #, no-wrap msgid "Preferred License for New Files" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2683 +#: documentation/content/en/articles/committers-guide/_index.adoc:2684 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:2685 +#: documentation/content/en/articles/committers-guide/_index.adoc:2686 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:2716 +#: documentation/content/en/articles/committers-guide/_index.adoc:2717 #, 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:2722 +#: documentation/content/en/articles/committers-guide/_index.adoc:2723 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:2726 +#: documentation/content/en/articles/committers-guide/_index.adoc:2727 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:2730 +#: documentation/content/en/articles/committers-guide/_index.adoc:2731 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:2733 +#: documentation/content/en/articles/committers-guide/_index.adoc:2734 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:2735 +#: documentation/content/en/articles/committers-guide/_index.adoc:2736 #, no-wrap msgid "Keeping Track of Licenses Granted to the FreeBSD Project" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2740 +#: documentation/content/en/articles/committers-guide/_index.adoc:2741 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:2745 +#: documentation/content/en/articles/committers-guide/_index.adoc:2746 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:2747 +#: documentation/content/en/articles/committers-guide/_index.adoc:2748 msgid "" "Contact details for people or organizations granting the special license." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2748 +#: documentation/content/en/articles/committers-guide/_index.adoc:2749 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:2749 +#: documentation/content/en/articles/committers-guide/_index.adoc:2750 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:2750 +#: documentation/content/en/articles/committers-guide/_index.adoc:2751 msgid "The license text." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2751 +#: documentation/content/en/articles/committers-guide/_index.adoc:2752 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:2752 +#: documentation/content/en/articles/committers-guide/_index.adoc:2753 msgid "Any other relevant information." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2755 +#: documentation/content/en/articles/committers-guide/_index.adoc:2756 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:2758 +#: documentation/content/en/articles/committers-guide/_index.adoc:2759 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:2760 +#: documentation/content/en/articles/committers-guide/_index.adoc:2761 #, no-wrap msgid "SPDX Tags in the tree" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2771 +#: documentation/content/en/articles/committers-guide/_index.adoc:2772 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/[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 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:2773 +#: documentation/content/en/articles/committers-guide/_index.adoc:2774 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:2774 +#: documentation/content/en/articles/committers-guide/_index.adoc:2775 #, no-wrap msgid "Developer Relations" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2780 +#: documentation/content/en/articles/committers-guide/_index.adoc:2781 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:2784 +#: documentation/content/en/articles/committers-guide/_index.adoc:2785 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:2788 +#: documentation/content/en/articles/committers-guide/_index.adoc:2789 #, 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:2791 +#: documentation/content/en/articles/committers-guide/_index.adoc:2792 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:2796 +#: documentation/content/en/articles/committers-guide/_index.adoc:2797 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:2802 +#: documentation/content/en/articles/committers-guide/_index.adoc:2803 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:2806 +#: documentation/content/en/articles/committers-guide/_index.adoc:2807 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:2809 +#: documentation/content/en/articles/committers-guide/_index.adoc:2810 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:2815 +#: documentation/content/en/articles/committers-guide/_index.adoc:2816 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:2819 +#: documentation/content/en/articles/committers-guide/_index.adoc:2820 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:2821 +#: documentation/content/en/articles/committers-guide/_index.adoc:2822 #, no-wrap msgid "If in Doubt..." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2825 +#: documentation/content/en/articles/committers-guide/_index.adoc:2826 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:2829 +#: documentation/content/en/articles/committers-guide/_index.adoc:2830 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:2831 +#: documentation/content/en/articles/committers-guide/_index.adoc:2832 msgid "For project specific or administrative questions ask, in order:" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2833 +#: documentation/content/en/articles/committers-guide/_index.adoc:2834 msgid "Your mentor or former mentor." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2834 +#: documentation/content/en/articles/committers-guide/_index.adoc:2835 msgid "An experienced committer on IRC, email, etc." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2835 +#: documentation/content/en/articles/committers-guide/_index.adoc:2836 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:2836 +#: documentation/content/en/articles/committers-guide/_index.adoc:2837 msgid "If still not sure, ask on {developers-name}." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2838 +#: documentation/content/en/articles/committers-guide/_index.adoc:2839 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:2840 +#: documentation/content/en/articles/committers-guide/_index.adoc:2841 #, no-wrap msgid "Bugzilla" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2845 +#: documentation/content/en/articles/committers-guide/_index.adoc:2846 msgid "" "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." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2847 +#: documentation/content/en/articles/committers-guide/_index.adoc:2848 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:2851 +#: documentation/content/en/articles/committers-guide/_index.adoc:2852 msgid "Log in using your old account." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2852 +#: documentation/content/en/articles/committers-guide/_index.adoc:2853 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:2853 +#: documentation/content/en/articles/committers-guide/_index.adoc:2854 msgid "" "Log in using `FreeBSD.org` account and post comment to newly opened bug to " "confirm ownership. See <> 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:2854 +#: documentation/content/en/articles/committers-guide/_index.adoc:2855 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:2857 +#: documentation/content/en/articles/committers-guide/_index.adoc:2858 msgid "You can find out more about Bugzilla at:" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2859 +#: documentation/content/en/articles/committers-guide/_index.adoc:2860 msgid "extref:{pr-guidelines}[FreeBSD Problem Report Handling Guidelines]" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2860 +#: documentation/content/en/articles/committers-guide/_index.adoc:2861 msgid "link:https://www.FreeBSD.org/support/[https://www.FreeBSD.org/support]" msgstr "" #. type: Title == -#: documentation/content/en/articles/committers-guide/_index.adoc:2862 +#: documentation/content/en/articles/committers-guide/_index.adoc:2863 #, no-wrap msgid "Phabricator" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2866 +#: documentation/content/en/articles/committers-guide/_index.adoc:2867 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:2868 +#: documentation/content/en/articles/committers-guide/_index.adoc:2869 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:2872 +#: documentation/content/en/articles/committers-guide/_index.adoc:2873 msgid "Change your Phabricator account email to your `FreeBSD.org` email." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2873 +#: documentation/content/en/articles/committers-guide/_index.adoc:2874 msgid "" "Open new bug on our bug tracker using your `FreeBSD.org` account, see " "<> 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:2878 +#: documentation/content/en/articles/committers-guide/_index.adoc:2879 msgid "" "Phabricator accounts cannot be merged, please do not open a new account." msgstr "" #. type: Title == -#: documentation/content/en/articles/committers-guide/_index.adoc:2881 +#: documentation/content/en/articles/committers-guide/_index.adoc:2882 #, no-wrap msgid "Who's Who" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2884 +#: documentation/content/en/articles/committers-guide/_index.adoc:2885 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:2885 +#: documentation/content/en/articles/committers-guide/_index.adoc:2886 #, no-wrap msgid "`{doceng}`" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2891 +#: documentation/content/en/articles/committers-guide/_index.adoc:2892 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:2892 +#: documentation/content/en/articles/committers-guide/_index.adoc:2893 #, no-wrap msgid "`{re-members}`" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2897 +#: documentation/content/en/articles/committers-guide/_index.adoc:2898 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:2898 +#: documentation/content/en/articles/committers-guide/_index.adoc:2899 #, no-wrap msgid "`{so}`" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2900 +#: documentation/content/en/articles/committers-guide/_index.adoc:2901 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:2905 +#: documentation/content/en/articles/committers-guide/_index.adoc:2906 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:2910 +#: documentation/content/en/articles/committers-guide/_index.adoc:2911 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:2914 +#: documentation/content/en/articles/committers-guide/_index.adoc:2915 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:2918 +#: documentation/content/en/articles/committers-guide/_index.adoc:2919 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:2924 +#: documentation/content/en/articles/committers-guide/_index.adoc:2925 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:2925 +#: documentation/content/en/articles/committers-guide/_index.adoc:2926 #, no-wrap msgid "SSH Quick-Start Guide" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2930 +#: documentation/content/en/articles/committers-guide/_index.adoc:2931 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:2931 +#: documentation/content/en/articles/committers-guide/_index.adoc:2932 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:2935 +#: documentation/content/en/articles/committers-guide/_index.adoc:2936 msgid "Only ECDSA, Ed25519 or RSA keys are supported." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:2937 +#: documentation/content/en/articles/committers-guide/_index.adoc:2938 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:2942 +#: documentation/content/en/articles/committers-guide/_index.adoc:2943 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:2944 +#: documentation/content/en/articles/committers-guide/_index.adoc:2945 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:2946 +#: documentation/content/en/articles/committers-guide/_index.adoc:2947 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:2948 +#: documentation/content/en/articles/committers-guide/_index.adoc:2949 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:2950 +#: documentation/content/en/articles/committers-guide/_index.adoc:2951 #, no-wrap msgid "Coverity(R) Availability for FreeBSD Committers" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2954 +#: documentation/content/en/articles/committers-guide/_index.adoc:2955 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:2957 +#: documentation/content/en/articles/committers-guide/_index.adoc:2958 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:2959 +#: documentation/content/en/articles/committers-guide/_index.adoc:2960 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:2961 +#: documentation/content/en/articles/committers-guide/_index.adoc:2962 #, no-wrap msgid "The FreeBSD Committers' Big List of Rules" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2966 +#: documentation/content/en/articles/committers-guide/_index.adoc:2967 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:2968 -#: documentation/content/en/articles/committers-guide/_index.adoc:2998 +#: documentation/content/en/articles/committers-guide/_index.adoc:2969 +#: documentation/content/en/articles/committers-guide/_index.adoc:2999 msgid "Respect other committers." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2969 -#: documentation/content/en/articles/committers-guide/_index.adoc:3014 +#: documentation/content/en/articles/committers-guide/_index.adoc:2970 +#: documentation/content/en/articles/committers-guide/_index.adoc:3015 msgid "Respect other contributors." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2970 -#: documentation/content/en/articles/committers-guide/_index.adoc:3029 +#: documentation/content/en/articles/committers-guide/_index.adoc:2971 +#: documentation/content/en/articles/committers-guide/_index.adoc:3030 msgid "Discuss any significant change _before_ committing." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2971 +#: documentation/content/en/articles/committers-guide/_index.adoc:2972 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:2972 -#: documentation/content/en/articles/committers-guide/_index.adoc:3044 +#: documentation/content/en/articles/committers-guide/_index.adoc:2973 +#: documentation/content/en/articles/committers-guide/_index.adoc:3045 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:2973 +#: documentation/content/en/articles/committers-guide/_index.adoc:2974 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:2974 -#: documentation/content/en/articles/committers-guide/_index.adoc:3059 +#: documentation/content/en/articles/committers-guide/_index.adoc:2975 +#: documentation/content/en/articles/committers-guide/_index.adoc:3060 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:2975 +#: documentation/content/en/articles/committers-guide/_index.adoc:2976 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:2976 -#: documentation/content/en/articles/committers-guide/_index.adoc:3074 +#: documentation/content/en/articles/committers-guide/_index.adoc:2977 +#: documentation/content/en/articles/committers-guide/_index.adoc:3075 msgid "When in doubt on any procedure, ask first!" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2977 -#: documentation/content/en/articles/committers-guide/_index.adoc:3079 +#: documentation/content/en/articles/committers-guide/_index.adoc:2978 +#: documentation/content/en/articles/committers-guide/_index.adoc:3080 msgid "Test your changes before committing them." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:2978 -#: documentation/content/en/articles/committers-guide/_index.adoc:3088 +#: documentation/content/en/articles/committers-guide/_index.adoc:2979 +#: documentation/content/en/articles/committers-guide/_index.adoc:3089 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:2989 +#: documentation/content/en/articles/committers-guide/_index.adoc:2990 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:2993 +#: documentation/content/en/articles/committers-guide/_index.adoc:2994 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:2994 +#: documentation/content/en/articles/committers-guide/_index.adoc:2995 #, no-wrap msgid "Details" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3002 +#: documentation/content/en/articles/committers-guide/_index.adoc:3003 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:3004 +#: documentation/content/en/articles/committers-guide/_index.adoc:3005 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:3010 +#: documentation/content/en/articles/committers-guide/_index.adoc:3011 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:3013 +#: documentation/content/en/articles/committers-guide/_index.adoc:3014 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:3026 +#: documentation/content/en/articles/committers-guide/_index.adoc:3027 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:3028 +#: documentation/content/en/articles/committers-guide/_index.adoc:3029 msgid "" "Consider the points raised under <> and " "apply them also to contributors." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3035 +#: documentation/content/en/articles/committers-guide/_index.adoc:3036 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:3037 +#: documentation/content/en/articles/committers-guide/_index.adoc:3038 msgid "When in doubt, ask for review!" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3038 +#: documentation/content/en/articles/committers-guide/_index.adoc:3039 msgid "Respect existing maintainers if listed." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3043 +#: documentation/content/en/articles/committers-guide/_index.adoc:3044 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:3049 +#: documentation/content/en/articles/committers-guide/_index.adoc:3050 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:3050 +#: documentation/content/en/articles/committers-guide/_index.adoc:3051 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:3056 +#: documentation/content/en/articles/committers-guide/_index.adoc:3057 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:3058 +#: documentation/content/en/articles/committers-guide/_index.adoc:3059 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:3069 +#: documentation/content/en/articles/committers-guide/_index.adoc:3070 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:3070 +#: documentation/content/en/articles/committers-guide/_index.adoc:3071 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:3073 +#: documentation/content/en/articles/committers-guide/_index.adoc:3074 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:3078 +#: documentation/content/en/articles/committers-guide/_index.adoc:3079 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:3087 +#: documentation/content/en/articles/committers-guide/_index.adoc:3088 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 make world. 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 <>. 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:3090 +#: documentation/content/en/articles/committers-guide/_index.adoc:3091 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:3095 +#: documentation/content/en/articles/committers-guide/_index.adoc:3096 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:3099 +#: documentation/content/en/articles/committers-guide/_index.adoc:3100 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:3102 +#: documentation/content/en/articles/committers-guide/_index.adoc:3103 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:3103 +#: documentation/content/en/articles/committers-guide/_index.adoc:3104 #, no-wrap msgid "Policy on Multiple Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3107 +#: documentation/content/en/articles/committers-guide/_index.adoc:3108 msgid "" "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:" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3111 +#: documentation/content/en/articles/committers-guide/_index.adoc:3112 msgid "" "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." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3115 +#: documentation/content/en/articles/committers-guide/_index.adoc:3116 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:3117 +#: documentation/content/en/articles/committers-guide/_index.adoc:3118 #, no-wrap msgid "Policy on Multiple Compilers" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3131 +#: documentation/content/en/articles/committers-guide/_index.adoc:3132 msgid "" "FreeBSD 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 unduely increasing the testing matrix. Older " "and obscure compilers, as well as older dialects of the langauges, 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:3136 +#: documentation/content/en/articles/committers-guide/_index.adoc:3137 msgid "" "The FreeBSD project provides 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:3144 +#: documentation/content/en/articles/committers-guide/_index.adoc:3145 msgid "" "At any moment in time, the FreeBSD project also supports one or more out-of-" "tree compilers. At present, this is GCC 12.x. Ideally, committers should " "test compile with this compiler, especially for large or risky changes. " "This compiler is available as the `${TARGET_ARCH}-gcc${VERSION}` package, " "such as package:devel/freebsd-gcc12@aarch64[aarch64-gcc12] or package:devel/" "freebsd-gcc12@riscv64[riscv64-gcc12]. 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 build with, for " "example `CROSS_TOOLCHAIN=aarch64-gcc12` or `CROSS_TOOLCHAIN=llvm15` where " "necessary." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3148 +#: documentation/content/en/articles/committers-guide/_index.adoc:3149 msgid "" "The FreeBSD project also has some CI pipelines on github. For pull requests " "on github and some branches pushed to the github forks, a number of cross " "compilation jobs run. These test FreeBSD building using a version of Clang " "that sometimes lags the in-tree compiler by a major version for a time." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3154 +#: documentation/content/en/articles/committers-guide/_index.adoc:3155 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:3158 +#: documentation/content/en/articles/committers-guide/_index.adoc:3159 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:3164 +#: documentation/content/en/articles/committers-guide/_index.adoc:3165 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:3169 +#: documentation/content/en/articles/committers-guide/_index.adoc:3170 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:3170 +#: documentation/content/en/articles/committers-guide/_index.adoc:3171 #, no-wrap msgid "Current Compiler Versions" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3175 +#: documentation/content/en/articles/committers-guide/_index.adoc:3176 msgid "" "The in-tree compiler is currently Clang 15.x. Currently, GCC 12 and Clang " "12, 13, 14 and 15 are tested in the github and project's CI jenkins jobs. " "Work is underway to get the tree ready for Clang 16. The oldest project " "supported branch has Clang 12, so the bootstrap portions of the build must " "work for Clang major versions 12 to 15." msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3176 +#: documentation/content/en/articles/committers-guide/_index.adoc:3177 #, no-wrap msgid "Other Suggestions" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3180 +#: documentation/content/en/articles/committers-guide/_index.adoc:3181 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:3182 +#: documentation/content/en/articles/committers-guide/_index.adoc:3183 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:3189 +#: documentation/content/en/articles/committers-guide/_index.adoc:3190 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:3190 +#: documentation/content/en/articles/committers-guide/_index.adoc:3191 #, no-wrap msgid "Deprecating Features" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3193 +#: documentation/content/en/articles/committers-guide/_index.adoc:3194 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:3195 +#: documentation/content/en/articles/committers-guide/_index.adoc:3196 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:3196 +#: documentation/content/en/articles/committers-guide/_index.adoc:3197 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:3197 +#: documentation/content/en/articles/committers-guide/_index.adoc:3198 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:3198 +#: documentation/content/en/articles/committers-guide/_index.adoc:3199 #, no-wrap msgid "Privacy and Confidentiality" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3201 +#: documentation/content/en/articles/committers-guide/_index.adoc:3202 msgid "Most FreeBSD business is done in public." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3204 +#: documentation/content/en/articles/committers-guide/_index.adoc:3205 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:3205 +#: documentation/content/en/articles/committers-guide/_index.adoc:3206 msgid "Certain sensitive matters must remain private or held under embargo." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3211 +#: documentation/content/en/articles/committers-guide/_index.adoc:3212 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:3212 +#: documentation/content/en/articles/committers-guide/_index.adoc:3213 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:3217 +#: documentation/content/en/articles/committers-guide/_index.adoc:3218 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:3218 +#: documentation/content/en/articles/committers-guide/_index.adoc:3219 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:3223 +#: documentation/content/en/articles/committers-guide/_index.adoc:3224 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:3224 +#: documentation/content/en/articles/committers-guide/_index.adoc:3225 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:3227 +#: documentation/content/en/articles/committers-guide/_index.adoc:3228 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:3228 +#: documentation/content/en/articles/committers-guide/_index.adoc:3229 msgid "Private communications must not be made public without permission." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3231 +#: documentation/content/en/articles/committers-guide/_index.adoc:3232 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:3232 +#: documentation/content/en/articles/committers-guide/_index.adoc:3233 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:3235 +#: documentation/content/en/articles/committers-guide/_index.adoc:3236 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:3236 +#: documentation/content/en/articles/committers-guide/_index.adoc:3237 msgid "Core may approve publication." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3238 +#: documentation/content/en/articles/committers-guide/_index.adoc:3239 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:3240 +#: documentation/content/en/articles/committers-guide/_index.adoc:3241 #, no-wrap msgid "Support for Multiple Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3247 +#: documentation/content/en/articles/committers-guide/_index.adoc:3248 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:3248 +#: documentation/content/en/articles/committers-guide/_index.adoc:3249 #, no-wrap msgid "Statement of General Intent" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3253 +#: documentation/content/en/articles/committers-guide/_index.adoc:3254 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:3260 +#: documentation/content/en/articles/committers-guide/_index.adoc:3261 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:3261 +#: documentation/content/en/articles/committers-guide/_index.adoc:3262 #, no-wrap msgid "Platform Targets" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3268 +#: documentation/content/en/articles/committers-guide/_index.adoc:3269 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:3270 +#: documentation/content/en/articles/committers-guide/_index.adoc:3271 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:3275 +#: documentation/content/en/articles/committers-guide/_index.adoc:3276 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:3277 +#: documentation/content/en/articles/committers-guide/_index.adoc:3278 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:3278 +#: documentation/content/en/articles/committers-guide/_index.adoc:3279 #, no-wrap msgid "Tier 1: Fully-Supported Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3283 +#: documentation/content/en/articles/committers-guide/_index.adoc:3284 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:3285 +#: documentation/content/en/articles/committers-guide/_index.adoc:3286 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:3287 +#: documentation/content/en/articles/committers-guide/_index.adoc:3288 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:3288 +#: documentation/content/en/articles/committers-guide/_index.adoc:3289 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:3289 +#: documentation/content/en/articles/committers-guide/_index.adoc:3290 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:3290 +#: documentation/content/en/articles/committers-guide/_index.adoc:3291 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:3291 +#: documentation/content/en/articles/committers-guide/_index.adoc:3292 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:3292 +#: documentation/content/en/articles/committers-guide/_index.adoc:3293 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:3293 +#: documentation/content/en/articles/committers-guide/_index.adoc:3294 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:3294 +#: documentation/content/en/articles/committers-guide/_index.adoc:3295 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:3295 +#: documentation/content/en/articles/committers-guide/_index.adoc:3296 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:3296 +#: documentation/content/en/articles/committers-guide/_index.adoc:3297 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:3297 +#: documentation/content/en/articles/committers-guide/_index.adoc:3298 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:3298 +#: documentation/content/en/articles/committers-guide/_index.adoc:3299 msgid "Tier 1 platforms will be included in the source tree." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3299 +#: documentation/content/en/articles/committers-guide/_index.adoc:3300 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:3301 +#: documentation/content/en/articles/committers-guide/_index.adoc:3302 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:3303 +#: documentation/content/en/articles/committers-guide/_index.adoc:3304 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:3304 -#: documentation/content/en/articles/committers-guide/_index.adoc:3334 +#: documentation/content/en/articles/committers-guide/_index.adoc:3305 +#: documentation/content/en/articles/committers-guide/_index.adoc:3335 msgid "Inclusion in the `make universe` and `make tinderbox` targets." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3305 +#: documentation/content/en/articles/committers-guide/_index.adoc:3306 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:3307 +#: documentation/content/en/articles/committers-guide/_index.adoc:3308 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:3309 +#: documentation/content/en/articles/committers-guide/_index.adoc:3310 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:3310 +#: documentation/content/en/articles/committers-guide/_index.adoc:3311 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:3311 +#: documentation/content/en/articles/committers-guide/_index.adoc:3312 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:3312 +#: documentation/content/en/articles/committers-guide/_index.adoc:3313 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:3313 +#: documentation/content/en/articles/committers-guide/_index.adoc:3314 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:3314 +#: documentation/content/en/articles/committers-guide/_index.adoc:3315 #, no-wrap msgid "Tier 2: Developmental and Niche Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3318 +#: documentation/content/en/articles/committers-guide/_index.adoc:3319 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:3322 +#: documentation/content/en/articles/committers-guide/_index.adoc:3323 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:3324 +#: documentation/content/en/articles/committers-guide/_index.adoc:3325 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:3326 +#: documentation/content/en/articles/committers-guide/_index.adoc:3327 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:3327 +#: documentation/content/en/articles/committers-guide/_index.adoc:3328 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:3328 +#: documentation/content/en/articles/committers-guide/_index.adoc:3329 msgid "Tier 2 platforms will be included in the source tree." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3329 +#: documentation/content/en/articles/committers-guide/_index.adoc:3330 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:3330 +#: documentation/content/en/articles/committers-guide/_index.adoc:3331 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:3332 +#: documentation/content/en/articles/committers-guide/_index.adoc:3333 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:3336 +#: documentation/content/en/articles/committers-guide/_index.adoc:3337 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:3338 +#: documentation/content/en/articles/committers-guide/_index.adoc:3339 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:3339 +#: documentation/content/en/articles/committers-guide/_index.adoc:3340 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:3340 +#: documentation/content/en/articles/committers-guide/_index.adoc:3341 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:3341 +#: documentation/content/en/articles/committers-guide/_index.adoc:3342 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:3342 +#: documentation/content/en/articles/committers-guide/_index.adoc:3343 #, no-wrap msgid "Tier 3: Experimental Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3346 +#: documentation/content/en/articles/committers-guide/_index.adoc:3347 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:3349 +#: documentation/content/en/articles/committers-guide/_index.adoc:3350 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:3352 +#: documentation/content/en/articles/committers-guide/_index.adoc:3353 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:3353 +#: documentation/content/en/articles/committers-guide/_index.adoc:3354 #, no-wrap msgid "Unsupported Architectures" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3357 +#: documentation/content/en/articles/committers-guide/_index.adoc:3358 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:3360 +#: documentation/content/en/articles/committers-guide/_index.adoc:3361 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:3361 +#: documentation/content/en/articles/committers-guide/_index.adoc:3362 #, no-wrap msgid "Policy on Changing the Tier of an Architecture" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3365 +#: documentation/content/en/articles/committers-guide/_index.adoc:3366 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:3367 +#: documentation/content/en/articles/committers-guide/_index.adoc:3368 #, no-wrap msgid "Ports Specific FAQ" msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3370 +#: documentation/content/en/articles/committers-guide/_index.adoc:3371 #, no-wrap msgid "Adding a New Port" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3373 +#: documentation/content/en/articles/committers-guide/_index.adoc:3374 #, no-wrap msgid "How do I add a new port?" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3377 +#: documentation/content/en/articles/committers-guide/_index.adoc:3378 msgid "" "Adding a port to the tree is relatively simple. Once the port is ready to be " "added, as explained later <>, 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:3381 +#: documentation/content/en/articles/committers-guide/_index.adoc:3382 #, no-wrap msgid "\tSUBDIR += newport\n" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3384 +#: documentation/content/en/articles/committers-guide/_index.adoc:3385 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:3389 +#: documentation/content/en/articles/committers-guide/_index.adoc:3390 #, 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:3393 +#: documentation/content/en/articles/committers-guide/_index.adoc:3394 msgid "" "Don't forget to <>; a specific hook has been developed to verify the " "category's [.filename]#Makefile#." msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3396 +#: documentation/content/en/articles/committers-guide/_index.adoc:3397 #, 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:3399 +#: documentation/content/en/articles/committers-guide/_index.adoc:3400 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:3402 +#: documentation/content/en/articles/committers-guide/_index.adoc:3403 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:3404 +#: documentation/content/en/articles/committers-guide/_index.adoc:3405 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:3406 +#: documentation/content/en/articles/committers-guide/_index.adoc:3407 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:3409 +#: documentation/content/en/articles/committers-guide/_index.adoc:3410 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:3413 +#: documentation/content/en/articles/committers-guide/_index.adoc:3414 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:3423 +#: documentation/content/en/articles/committers-guide/_index.adoc:3424 #, 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:3426 +#: documentation/content/en/articles/committers-guide/_index.adoc:3427 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:3429 +#: documentation/content/en/articles/committers-guide/_index.adoc:3430 #, no-wrap msgid "Removing an Existing Port" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3432 +#: documentation/content/en/articles/committers-guide/_index.adoc:3433 #, no-wrap msgid "How do I remove an existing port?" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3435 +#: documentation/content/en/articles/committers-guide/_index.adoc:3436 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:3437 +#: documentation/content/en/articles/committers-guide/_index.adoc:3438 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:3438 +#: documentation/content/en/articles/committers-guide/_index.adoc:3439 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:3439 +#: documentation/content/en/articles/committers-guide/_index.adoc:3440 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:3443 +#: documentation/content/en/articles/committers-guide/_index.adoc:3444 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:3446 +#: documentation/content/en/articles/committers-guide/_index.adoc:3447 msgid "Then, remove the port:" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3450 +#: documentation/content/en/articles/committers-guide/_index.adoc:3451 msgid "Remove the port's files and directory with `git rm`." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3451 +#: documentation/content/en/articles/committers-guide/_index.adoc:3452 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:3452 -#: documentation/content/en/articles/committers-guide/_index.adoc:3467 +#: documentation/content/en/articles/committers-guide/_index.adoc:3453 +#: documentation/content/en/articles/committers-guide/_index.adoc:3468 msgid "Add an entry to [.filename]#ports/MOVED#." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3453 +#: documentation/content/en/articles/committers-guide/_index.adoc:3454 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:3458 +#: documentation/content/en/articles/committers-guide/_index.adoc:3459 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:3460 +#: documentation/content/en/articles/committers-guide/_index.adoc:3461 #, 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:3465 +#: documentation/content/en/articles/committers-guide/_index.adoc:3466 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:3466 +#: documentation/content/en/articles/committers-guide/_index.adoc:3467 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:3468 +#: documentation/content/en/articles/committers-guide/_index.adoc:3469 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:3469 +#: documentation/content/en/articles/committers-guide/_index.adoc:3470 msgid "Move the port with `git mv`." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3470 -#: documentation/content/en/articles/committers-guide/_index.adoc:3481 +#: documentation/content/en/articles/committers-guide/_index.adoc:3471 +#: documentation/content/en/articles/committers-guide/_index.adoc:3482 msgid "Commit the changes." msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3473 +#: documentation/content/en/articles/committers-guide/_index.adoc:3474 #, 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:3478 +#: documentation/content/en/articles/committers-guide/_index.adoc:3479 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:3479 +#: documentation/content/en/articles/committers-guide/_index.adoc:3480 msgid "Add the new port to the [.filename]#new-cat/Makefile#." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3480 +#: documentation/content/en/articles/committers-guide/_index.adoc:3481 msgid "Change stuff in [.filename]#new-cat/new-port#." msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3484 +#: documentation/content/en/articles/committers-guide/_index.adoc:3485 #, no-wrap msgid "Ports Freeze" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3487 +#: documentation/content/en/articles/committers-guide/_index.adoc:3488 #, no-wrap msgid "What is a “ports freeze”?" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3494 +#: documentation/content/en/articles/committers-guide/_index.adoc:3495 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:3496 +#: documentation/content/en/articles/committers-guide/_index.adoc:3497 msgid "" "For more information on how to merge commits to the quarterly branch, see " "<>." msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3498 +#: documentation/content/en/articles/committers-guide/_index.adoc:3499 #, no-wrap msgid "Quarterly Branches" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3501 +#: documentation/content/en/articles/committers-guide/_index.adoc:3502 #, 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:3504 +#: documentation/content/en/articles/committers-guide/_index.adoc:3505 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:3506 +#: documentation/content/en/articles/committers-guide/_index.adoc:3507 #, 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:3509 +#: documentation/content/en/articles/committers-guide/_index.adoc:3510 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:3515 +#: documentation/content/en/articles/committers-guide/_index.adoc:3516 #, 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:3519 +#: documentation/content/en/articles/committers-guide/_index.adoc:3520 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:3521 +#: documentation/content/en/articles/committers-guide/_index.adoc:3522 #, no-wrap msgid "Creating a New Category" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3524 +#: documentation/content/en/articles/committers-guide/_index.adoc:3525 #, no-wrap msgid "What is the procedure for creating a new category?" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3529 +#: documentation/content/en/articles/committers-guide/_index.adoc:3530 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:3533 +#: documentation/content/en/articles/committers-guide/_index.adoc:3534 msgid "Perform any needed moves. (This only applies to physical categories.)" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3534 +#: documentation/content/en/articles/committers-guide/_index.adoc:3535 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:3535 +#: documentation/content/en/articles/committers-guide/_index.adoc:3536 msgid "Assign the PR back to you." msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3538 +#: documentation/content/en/articles/committers-guide/_index.adoc:3539 #, 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:3543 +#: documentation/content/en/articles/committers-guide/_index.adoc:3544 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:3545 +#: documentation/content/en/articles/committers-guide/_index.adoc:3546 msgid "To do this, you will need to:" msgstr "" #. type: delimited block = 6 -#: documentation/content/en/articles/committers-guide/_index.adoc:3549 +#: documentation/content/en/articles/committers-guide/_index.adoc:3550 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:3550 +#: documentation/content/en/articles/committers-guide/_index.adoc:3551 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:3551 +#: documentation/content/en/articles/committers-guide/_index.adoc:3552 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:3554 +#: documentation/content/en/articles/committers-guide/_index.adoc:3555 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:3556 +#: documentation/content/en/articles/committers-guide/_index.adoc:3557 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:3557 +#: documentation/content/en/articles/committers-guide/_index.adoc:3558 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:3558 +#: documentation/content/en/articles/committers-guide/_index.adoc:3559 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:3559 +#: documentation/content/en/articles/committers-guide/_index.adoc:3560 msgid "Add appropriate entries to [.filename]#ports/MOVED#." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3560 +#: documentation/content/en/articles/committers-guide/_index.adoc:3561 msgid "Update the documentation by modifying:" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3561 -#: documentation/content/en/articles/committers-guide/_index.adoc:3570 +#: documentation/content/en/articles/committers-guide/_index.adoc:3562 +#: documentation/content/en/articles/committers-guide/_index.adoc:3571 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:3563 +#: documentation/content/en/articles/committers-guide/_index.adoc:3564 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:3565 +#: documentation/content/en/articles/committers-guide/_index.adoc:3566 #, 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:3568 +#: documentation/content/en/articles/committers-guide/_index.adoc:3569 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:3572 -#: documentation/content/en/articles/committers-guide/_index.adoc:3666 +#: documentation/content/en/articles/committers-guide/_index.adoc:3573 +#: documentation/content/en/articles/committers-guide/_index.adoc:3667 #, no-wrap msgid "Miscellaneous Questions" msgstr "" #. type: Title ==== -#: documentation/content/en/articles/committers-guide/_index.adoc:3575 +#: documentation/content/en/articles/committers-guide/_index.adoc:3576 #, 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:3578 +#: documentation/content/en/articles/committers-guide/_index.adoc:3579 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:3580 +#: documentation/content/en/articles/committers-guide/_index.adoc:3581 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:3581 +#: documentation/content/en/articles/committers-guide/_index.adoc:3582 msgid "Trivial and _tested_ build and runtime fixes." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3582 +#: documentation/content/en/articles/committers-guide/_index.adoc:3583 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:3587 +#: documentation/content/en/articles/committers-guide/_index.adoc:3588 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:3590 +#: documentation/content/en/articles/committers-guide/_index.adoc:3591 #, 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:3594 +#: documentation/content/en/articles/committers-guide/_index.adoc:3595 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:3596 +#: documentation/content/en/articles/committers-guide/_index.adoc:3597 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:3598 +#: documentation/content/en/articles/committers-guide/_index.adoc:3599 #, 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:3601 +#: documentation/content/en/articles/committers-guide/_index.adoc:3602 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:3603 +#: documentation/content/en/articles/committers-guide/_index.adoc:3604 #, 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:3607 +#: documentation/content/en/articles/committers-guide/_index.adoc:3608 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:3609 +#: documentation/content/en/articles/committers-guide/_index.adoc:3610 #, 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:3613 +#: documentation/content/en/articles/committers-guide/_index.adoc:3614 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:3615 +#: documentation/content/en/articles/committers-guide/_index.adoc:3616 #, 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:3619 +#: documentation/content/en/articles/committers-guide/_index.adoc:3620 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:3621 +#: documentation/content/en/articles/committers-guide/_index.adoc:3622 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:3625 +#: documentation/content/en/articles/committers-guide/_index.adoc:3626 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:3626 +#: documentation/content/en/articles/committers-guide/_index.adoc:3627 msgid "Select the product your patch is about." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3627 +#: documentation/content/en/articles/committers-guide/_index.adoc:3628 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:3628 +#: documentation/content/en/articles/committers-guide/_index.adoc:3629 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:3629 +#: documentation/content/en/articles/committers-guide/_index.adoc:3630 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:3630 +#: documentation/content/en/articles/committers-guide/_index.adoc:3631 msgid "Submit. Wait for the build to run." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3631 +#: documentation/content/en/articles/committers-guide/_index.adoc:3632 msgid "{portmgr} will reply with a possible fallout." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3632 +#: documentation/content/en/articles/committers-guide/_index.adoc:3633 msgid "Depending on the fallout:" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3633 +#: documentation/content/en/articles/committers-guide/_index.adoc:3634 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:3634 +#: documentation/content/en/articles/committers-guide/_index.adoc:3635 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:3635 +#: documentation/content/en/articles/committers-guide/_index.adoc:3636 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:3638 +#: documentation/content/en/articles/committers-guide/_index.adoc:3639 #, no-wrap msgid "Issues Specific to Developers Who Are Not Committers" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3643 +#: documentation/content/en/articles/committers-guide/_index.adoc:3644 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:3645 +#: documentation/content/en/articles/committers-guide/_index.adoc:3646 msgid "<>" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3646 +#: documentation/content/en/articles/committers-guide/_index.adoc:3647 msgid "<>" msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3650 +#: documentation/content/en/articles/committers-guide/_index.adoc:3651 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:3652 +#: documentation/content/en/articles/committers-guide/_index.adoc:3653 msgid "<>" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3653 +#: documentation/content/en/articles/committers-guide/_index.adoc:3654 msgid "<>" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3654 +#: documentation/content/en/articles/committers-guide/_index.adoc:3655 msgid "<>" msgstr "" #. type: Title == -#: documentation/content/en/articles/committers-guide/_index.adoc:3656 +#: documentation/content/en/articles/committers-guide/_index.adoc:3657 #, no-wrap msgid "Information About Google Analytics" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3659 +#: documentation/content/en/articles/committers-guide/_index.adoc:3660 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:3663 +#: documentation/content/en/articles/committers-guide/_index.adoc:3664 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:3668 +#: documentation/content/en/articles/committers-guide/_index.adoc:3669 #, 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:3672 +#: documentation/content/en/articles/committers-guide/_index.adoc:3673 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:3673 +#: documentation/content/en/articles/committers-guide/_index.adoc:3674 #, no-wrap msgid "Where are the mailing list archives stored?" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3676 +#: documentation/content/en/articles/committers-guide/_index.adoc:3677 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:3677 +#: documentation/content/en/articles/committers-guide/_index.adoc:3678 #, 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:3680 +#: documentation/content/en/articles/committers-guide/_index.adoc:3681 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:3682 +#: documentation/content/en/articles/committers-guide/_index.adoc:3683 #, no-wrap msgid "Benefits and Perks for FreeBSD Committers" msgstr "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3685 +#: documentation/content/en/articles/committers-guide/_index.adoc:3686 #, no-wrap msgid "Recognition" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3689 +#: documentation/content/en/articles/committers-guide/_index.adoc:3690 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:3691 +#: documentation/content/en/articles/committers-guide/_index.adoc:3692 #, no-wrap msgid "FreeBSD Mall" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3694 +#: documentation/content/en/articles/committers-guide/_index.adoc:3695 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:3696 +#: documentation/content/en/articles/committers-guide/_index.adoc:3697 #, no-wrap msgid "`Gandi.net`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3699 +#: documentation/content/en/articles/committers-guide/_index.adoc:3700 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:3703 +#: documentation/content/en/articles/committers-guide/_index.adoc:3704 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:3705 +#: documentation/content/en/articles/committers-guide/_index.adoc:3706 #, no-wrap msgid "`rsync.net`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3708 +#: documentation/content/en/articles/committers-guide/_index.adoc:3709 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:3710 +#: documentation/content/en/articles/committers-guide/_index.adoc:3711 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 "" #. type: Title === -#: documentation/content/en/articles/committers-guide/_index.adoc:3712 +#: documentation/content/en/articles/committers-guide/_index.adoc:3713 #, no-wrap msgid "`JetBrains`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3715 +#: documentation/content/en/articles/committers-guide/_index.adoc:3716 msgid "" "https://www.jetbrains.com[JetBrains] is a software development company which " "makes tools for software developers and project managers. The company offers " "many integrated development environments (IDEs) for different programming " "languages." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/articles/committers-guide/_index.adoc:3717 +#: documentation/content/en/articles/committers-guide/_index.adoc:3718 msgid "" "JetBrains offers 100 free yearly licenses for all https://www.jetbrains.com/" "products[JetBrains IDE products]. Simply sign up at https://account." "jetbrains.com/a/322tl3z7[https://account.jetbrains.com/a/322tl3z7] using " "your `@freebsd.org` address and the account will have a license attached to " "it automatically. Once the account is active, use it in any of the products " "to activate them and you're done." msgstr "" #. type: Plain text -#: documentation/content/en/articles/committers-guide/_index.adoc:3721 +#: documentation/content/en/articles/committers-guide/_index.adoc:3722 msgid "" "Please, only use these licences personally and do not share them with anyone " "outside of the FreeBSD project, as that would be a violation of the terms of " "the donation." msgstr "" diff --git a/documentation/content/en/articles/linux-users/_index.po b/documentation/content/en/articles/linux-users/_index.po index 5c9083d37f..af81989e61 100644 --- a/documentation/content/en/articles/linux-users/_index.po +++ b/documentation/content/en/articles/linux-users/_index.po @@ -1,809 +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 , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-04-20 20:56-0300\n" +"POT-Creation-Date: 2023-06-19 21:08-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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://www." "freebsd.org/ports/[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 mtu 1500\n" " options=b\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 )\n" " status: active\n" "em1: flags=8843 mtu 1500\n" " options=b\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 )\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 Subversion servers. Once " -"the local source code is up-to-date, a new version of the kernel and " -"userland can be compiled." +"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/pgpkeys/_index.po b/documentation/content/en/articles/pgpkeys/_index.po index a2e554a8a4..7275554130 100644 --- a/documentation/content/en/articles/pgpkeys/_index.po +++ b/documentation/content/en/articles/pgpkeys/_index.po @@ -1,2860 +1,2866 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-05-21 14:43-0300\n" +"POT-Creation-Date: 2023-06-19 21:08-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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:342 #, no-wrap msgid "`{bapt}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:81 -#: documentation/content/en/articles/pgpkeys/_index.adoc:1089 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1092 #, no-wrap msgid "`{bcr}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:84 #: documentation/content/en/articles/pgpkeys/_index.adoc:762 #, no-wrap msgid "`{grog}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:87 #: documentation/content/en/articles/pgpkeys/_index.adoc:171 #, no-wrap msgid "`{jhb}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:90 #: documentation/content/en/articles/pgpkeys/_index.adoc:579 #, no-wrap msgid "`{lwhsu}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:93 -#: documentation/content/en/articles/pgpkeys/_index.adoc:1350 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1353 #, no-wrap msgid "`{manu}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:96 #: documentation/content/en/articles/pgpkeys/_index.adoc:198 #, no-wrap msgid "`{tcberner}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:99 -#: documentation/content/en/articles/pgpkeys/_index.adoc:1041 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1044 #, no-wrap msgid "`{0mp}`" 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:147 #, no-wrap msgid "`{mat}`" 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: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 "`{novel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:213 #, no-wrap msgid "`{garga}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:216 #, no-wrap msgid "`{kbowling}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:219 #, no-wrap msgid "`{alexbl}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:222 #, no-wrap msgid "`{ebrandi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:225 #, no-wrap msgid "`{harti}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:228 #, no-wrap msgid "`{obraun}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:231 #, no-wrap msgid "`{makc}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:234 #, no-wrap msgid "`{jmb}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:237 #, no-wrap msgid "`{antoine}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:240 #, no-wrap msgid "`{db}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:243 #, no-wrap msgid "`{brueffer}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:246 #, no-wrap msgid "`{markus}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:249 #, no-wrap msgid "`{br}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:252 #, no-wrap msgid "`{jch}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:255 #, no-wrap msgid "`{jchandra}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:258 #, no-wrap msgid "`{jcamou}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:261 #, no-wrap msgid "`{acm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:264 #, no-wrap msgid "`{gahr}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:267 #, no-wrap msgid "`{dchagin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:270 #, no-wrap msgid "`{perky}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:273 #, no-wrap msgid "`{jon}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:276 #, no-wrap msgid "`{jonathan}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:279 #, no-wrap msgid "`{loader}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:282 #, no-wrap msgid "`{luoqi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:285 #, no-wrap msgid "`{ache}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:288 #, no-wrap msgid "`{melifaro}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:291 #, no-wrap msgid "`{cjh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:294 #, no-wrap msgid "`{davidch}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:297 #, no-wrap msgid "`{milki}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:300 #, no-wrap msgid "`{cjc}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:303 #, no-wrap msgid "`{marcus}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:306 #, no-wrap msgid "`{fuz}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:309 #, no-wrap msgid "`{nik}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:312 #, no-wrap msgid "`{benjsc}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:315 #, no-wrap msgid "`{lcook}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:318 #, no-wrap msgid "`{ngie}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:321 #, no-wrap msgid "`{rakuco}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:324 #, no-wrap msgid "`{alc}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:327 #, no-wrap msgid "`{olivier}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:330 #, no-wrap msgid "`{bcran}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:333 #, no-wrap msgid "`{cc}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:336 #, no-wrap msgid "`{culot}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:339 #, no-wrap msgid "`{alfredo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:345 #, no-wrap msgid "`{ceri}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:348 #, no-wrap msgid "`{edavis}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:351 #, no-wrap msgid "`{alexey}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:354 #, no-wrap msgid "`{bsd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:357 #, no-wrap msgid "`{carl}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:360 #, no-wrap msgid "`{carlavilla}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:363 #, no-wrap msgid "`{vd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:366 #, no-wrap msgid "`{rdivacky}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:369 #, no-wrap msgid "`{danfe}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:372 #, no-wrap msgid "`{dd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:375 #, no-wrap msgid "`{bdrewery}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:378 #, no-wrap msgid "`{gad}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:381 #, no-wrap msgid "`{kd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:384 #, no-wrap msgid "`{olivierd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:387 #, no-wrap msgid "`{bruno}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:390 #, no-wrap msgid "`{ale}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:393 #, no-wrap msgid "`{nemysis}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:396 #, no-wrap msgid "`{peadar}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:399 #, no-wrap msgid "`{deischen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:402 #, no-wrap msgid "`{diizzy}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:405 #, no-wrap msgid "`{ue}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:408 #, no-wrap msgid "`{madpilot}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:411 #, no-wrap msgid "`{rafan}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:414 #, no-wrap msgid "`{kami}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:417 #, no-wrap msgid "`{farrokhi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:420 #, no-wrap msgid "`{jedgar}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:423 #, no-wrap msgid "`{mfechner}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:426 #, no-wrap msgid "`{feld}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:429 #, no-wrap msgid "`{green}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:432 #, no-wrap msgid "`{fanf}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:435 #, no-wrap msgid "`{blackend}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:438 #, no-wrap msgid "`{petef}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:441 #, no-wrap msgid "`{decke}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:444 #, no-wrap msgid "`{landonf}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:447 #, no-wrap msgid "`{billf}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:450 #, no-wrap msgid "`{grembo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:453 #, no-wrap msgid "`{sgalabov}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:456 #, no-wrap msgid "`{avg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:459 #, no-wrap msgid "`{beat}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:462 #, no-wrap msgid "`{sjg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:465 #, no-wrap msgid "`{gibbs}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:468 #, no-wrap msgid "`{pfg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:471 #, no-wrap msgid "`{girgen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:474 #, no-wrap msgid "`{eugen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:477 #, no-wrap msgid "`{pgollucci}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:480 #, no-wrap msgid "`{trociny}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:483 #, no-wrap msgid "`{dmgk}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:486 #, no-wrap msgid "`{daichi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:489 #, no-wrap msgid "`{grehan}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:492 #, no-wrap msgid "`{jamie}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:495 #, no-wrap msgid "`{adridg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:498 #, no-wrap msgid "`{wg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:501 #, no-wrap msgid "`{bar}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:504 #, no-wrap msgid "`{jmg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:507 #, no-wrap msgid "`{mjg}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:510 #, no-wrap msgid "`{jhale}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:513 #, no-wrap msgid "`{jah}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:516 #, no-wrap msgid "`{dannyboy}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:519 #, no-wrap msgid "`{dhartmei}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:522 #, no-wrap msgid "`{ohauer}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:525 #, no-wrap msgid "`{ehaupt}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:528 #, no-wrap msgid "`{jhay}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:531 #, no-wrap msgid "`{bhd}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:534 #, no-wrap msgid "`{sheldonh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:537 #, no-wrap msgid "`{mikeh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:540 #, no-wrap msgid "`{mheinen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:543 #, no-wrap msgid "`{niels}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:546 #, no-wrap msgid "`{ghelmer}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:549 #, no-wrap msgid "`{mux}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:552 #, no-wrap msgid "`{wen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:555 #, no-wrap msgid "`{dhn}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:558 #, no-wrap msgid "`{jhibbits}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:561 #, no-wrap msgid "`{jhixson}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:564 #, no-wrap msgid "`{pho}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:567 #, no-wrap msgid "`{oh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:570 #, no-wrap msgid "`{mhorne}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:573 #, no-wrap msgid "`{bhughes}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:576 #, no-wrap msgid "`{sunpoet}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:582 #, no-wrap msgid "`{foxfair}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:585 #, no-wrap msgid "`{whu}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:588 #, no-wrap msgid "`{chinsan}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:591 #, no-wrap msgid "`{zlei}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:594 #, no-wrap msgid "`{davide}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:597 #, no-wrap msgid "`{jkh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:600 #, no-wrap msgid "`{versus}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:603 #, no-wrap msgid "`{pi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:606 #, no-wrap msgid "`{weongyo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:609 #, no-wrap msgid "`{peterj}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:612 #, no-wrap msgid "`{jinmei}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:615 #, no-wrap msgid "`{ahze}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:618 #, no-wrap msgid "`{markj}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:621 #, no-wrap msgid "`{trevor}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:624 #, no-wrap msgid "`{erj}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:627 #, no-wrap msgid "`{allanjude}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:630 #, no-wrap msgid "`{bjk}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:633 #, no-wrap msgid "`{phk}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:636 #, no-wrap msgid "`{pluknet}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:639 #, no-wrap msgid "`{cokane}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:642 #, no-wrap msgid "`{karels}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:645 #, no-wrap msgid "`{kato}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:648 #, no-wrap msgid "`{vkashyap}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:651 #, no-wrap msgid "`{pkubaj}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:654 #, no-wrap msgid "`{kris}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:657 #, no-wrap msgid "`{keramida}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:660 #, no-wrap msgid "`{fjoe}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:663 #, no-wrap msgid "`{manolis}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:666 #, no-wrap msgid "`{stevek}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:669 #, no-wrap msgid "`{jkim}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:672 #, no-wrap msgid "`{zack}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:675 #, no-wrap msgid "`{jceel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:678 #, no-wrap msgid "`{andreas}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:681 #, no-wrap msgid "`{kai}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:684 #, no-wrap msgid "`{corvink}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:687 #, no-wrap msgid "`{jkois}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:690 #, no-wrap msgid "`{sergei}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:693 #, no-wrap msgid "`{maxim}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:696 #, no-wrap msgid "`{taras}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:699 #, no-wrap msgid "`{tobik}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:702 #, no-wrap msgid "`{jkoshy}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:705 #, no-wrap msgid "`{wkoszek}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:708 #, no-wrap msgid "`{ak}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:711 #, no-wrap msgid "`{gabor}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:714 #, no-wrap msgid "`{anchie}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:717 #, no-wrap msgid "`{rushani}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:720 #, no-wrap msgid "`{kuriyama}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:723 #, no-wrap msgid "`{rene}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:726 #, no-wrap msgid "`{jlaffaye}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:729 #, no-wrap msgid "`{clement}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:732 #, no-wrap msgid "`{mlaier}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:735 #, no-wrap msgid "`{martymac}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:738 #, no-wrap msgid "`{glarkin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:741 #, no-wrap msgid "`{dru}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:744 #, no-wrap msgid "`{lawrance}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:747 #, no-wrap msgid "`{njl}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:750 #, no-wrap msgid "`{jlh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:753 #, no-wrap msgid "`{leeym}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:756 #, no-wrap msgid "`{sam}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:759 #, no-wrap msgid "`{jylefort}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:765 #, no-wrap msgid "`{oliver}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:768 #, no-wrap msgid "`{netchild}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:771 #, no-wrap msgid "`{leitao}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:774 #, no-wrap msgid "`{ae}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:777 #, no-wrap msgid "`{lesi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:780 #, no-wrap msgid "`{achim}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:783 #, no-wrap msgid "`{cel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:786 #, no-wrap msgid "`{glewis}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:789 #, no-wrap msgid "`{vishwin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:792 #, no-wrap msgid "`{delphij}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:795 #, no-wrap msgid "`{avatar}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:798 #, no-wrap msgid "`{ijliao}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:801 #, no-wrap msgid "`{rlibby}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:804 #, no-wrap msgid "`{pclin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:807 #, no-wrap msgid "`{yzlin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:810 #, no-wrap msgid "`{linimon}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:813 #, no-wrap msgid "`{arved}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:816 #, no-wrap msgid "`{dryice}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:819 #, no-wrap msgid "`{nemoliu}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:822 #, no-wrap msgid "`{kevlo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:825 #, no-wrap msgid "`{zml}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:828 #, no-wrap msgid "`{nox}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:831 #, no-wrap msgid "`{avl}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:834 #, no-wrap msgid "`{scottl}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:837 #, no-wrap msgid "`{rmacklem}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:840 #, no-wrap msgid "`{vmaffione}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:843 #, no-wrap msgid "`{bmah}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:846 #, no-wrap msgid "`{rm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:849 #, no-wrap msgid "`{mtm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:852 #, no-wrap msgid "`{dwmalone}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:855 #, no-wrap -msgid "`{marino}`" +msgid "`{christos}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:858 #, no-wrap -msgid "`{cherry}`" +msgid "`{marino}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:861 #, no-wrap -msgid "`{matusita}`" +msgid "`{cherry}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:864 #, no-wrap -msgid "`{mm}`" +msgid "`{matusita}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:867 #, no-wrap -msgid "`{sem}`" +msgid "`{mm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:870 #, no-wrap -msgid "`{mckusick}`" +msgid "`{sem}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:873 #, no-wrap -msgid "`{tmclaugh}`" +msgid "`{mckusick}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:876 #, no-wrap -msgid "`{jmelo}`" +msgid "`{tmclaugh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:879 #, no-wrap -msgid "`{mmel}`" +msgid "`{jmelo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:882 #, no-wrap -msgid "`{jmmv}`" +msgid "`{mmel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:885 #, no-wrap -msgid "`{kadesai}`" +msgid "`{jmmv}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:888 #, no-wrap -msgid "`{ken}`" +msgid "`{kadesai}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:891 #, no-wrap -msgid "`{markm}`" +msgid "`{ken}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:894 #, no-wrap -msgid "`{dinoex}`" +msgid "`{markm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:897 #, no-wrap -msgid "`{sanpei}`" +msgid "`{dinoex}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:900 #, no-wrap -msgid "`{rmh}`" +msgid "`{sanpei}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:903 #, no-wrap -msgid "`{driesm}`" +msgid "`{rmh}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:906 #, no-wrap -msgid "`{jrm}`" +msgid "`{driesm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:909 #, no-wrap -msgid "`{freqlabs}`" +msgid "`{jrm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:912 #, no-wrap -msgid "`{mmoll}`" +msgid "`{freqlabs}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:915 #, no-wrap -msgid "`{cmt}`" +msgid "`{mmoll}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:918 #, no-wrap -msgid "`{stephen}`" +msgid "`{cmt}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:921 #, no-wrap -msgid "`{marcel}`" +msgid "`{stephen}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:924 #, no-wrap -msgid "`{dougm}`" +msgid "`{marcel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:927 #, no-wrap -msgid "`{kmoore}`" +msgid "`{dougm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:930 #, no-wrap -msgid "`{marck}`" +msgid "`{kmoore}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:933 #, no-wrap -msgid "`{mav}`" +msgid "`{marck}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:936 #, no-wrap -msgid "`{rich}`" +msgid "`{mav}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:939 #, no-wrap -msgid "`{knu}`" +msgid "`{rich}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:942 #, no-wrap -msgid "`{tmm}`" +msgid "`{knu}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:945 #, no-wrap -msgid "`{max}`" +msgid "`{tmm}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:948 #, no-wrap -msgid "`{maho}`" +msgid "`{max}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:951 #, no-wrap -msgid "`{yoichi}`" +msgid "`{maho}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:954 #, no-wrap -msgid "`{bland}`" +msgid "`{yoichi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:957 #, no-wrap -msgid "`{gnn}`" +msgid "`{bland}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:960 #, no-wrap -msgid "`{khng}`" +msgid "`{gnn}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:963 #, no-wrap -msgid "`{simon}`" +msgid "`{khng}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:966 #, no-wrap -msgid "`{rnoland}`" +msgid "`{simon}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:969 #, no-wrap -msgid "`{anders}`" +msgid "`{rnoland}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:972 #, no-wrap -msgid "`{lofi}`" +msgid "`{anders}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:975 #, no-wrap -msgid "`{obrien}`" +msgid "`{lofi}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:978 #, no-wrap -msgid "`{olgeni}`" +msgid "`{obrien}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:981 #, no-wrap -msgid "`{philip}`" +msgid "`{olgeni}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:984 #, no-wrap -msgid "`{jpaetzel}`" +msgid "`{philip}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:987 #, no-wrap -msgid "`{zirias}`" +msgid "`{jpaetzel}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:990 #, no-wrap -msgid "`{hiren}`" +msgid "`{zirias}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:993 #, no-wrap -msgid "`{hmp}`" +msgid "`{hiren}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:996 #, no-wrap -msgid "`{fluffy}`" +msgid "`{hmp}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:999 #, no-wrap -msgid "`{sat}`" +msgid "`{fluffy}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1002 #, no-wrap -msgid "`{np}`" +msgid "`{sat}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1005 #, no-wrap -msgid "`{royger}`" +msgid "`{np}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1008 #, no-wrap -msgid "`{rpaulo}`" +msgid "`{royger}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1011 #, no-wrap -msgid "`{misha}`" +msgid "`{rpaulo}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1014 #, no-wrap -msgid "`{rpokala}`" +msgid "`{misha}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1017 #, no-wrap -msgid "`{mp}`" +msgid "`{rpokala}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1020 #, no-wrap -msgid "`{roam}`" +msgid "`{mp}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1023 #, no-wrap -msgid "`{den}`" +msgid "`{roam}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1026 #, no-wrap -msgid "`{csjp}`" +msgid "`{den}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1029 #, no-wrap -msgid "`{grahamperrin}`" +msgid "`{csjp}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1032 #, no-wrap -msgid "`{gerald}`" +msgid "`{grahamperrin}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1035 #, no-wrap -msgid "`{scottph}`" +msgid "`{gerald}`" msgstr "" #. type: Title === #: documentation/content/en/articles/pgpkeys/_index.adoc:1038 #, no-wrap +msgid "`{scottph}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1041 +#, no-wrap msgid "`{jacula}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1044 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1047 #, no-wrap msgid "`{jdp}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1047 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1050 #, no-wrap msgid "`{krion}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1050 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1053 #, no-wrap msgid "`{sepotvin}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1053 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1056 #, no-wrap msgid "`{cpm}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1056 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1059 #, no-wrap msgid "`{markp}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1059 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1062 #, no-wrap msgid "`{alepulver}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1062 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1065 #, no-wrap msgid "`{kp}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1065 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1068 #, no-wrap msgid "`{thomas}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1068 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1071 #, no-wrap msgid "`{hq}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1071 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1074 #, no-wrap msgid "`{bofh}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1074 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1077 #, no-wrap msgid "`{fox}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1077 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1080 #, no-wrap msgid "`{lbr}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1080 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1083 #, no-wrap msgid "`{crees}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1083 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1086 #, no-wrap msgid "`{rees}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1086 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1089 #, no-wrap msgid "`{mr}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1092 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1095 #, no-wrap msgid "`{trhodes}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1095 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1098 #, no-wrap msgid "`{benno}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1098 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1101 #, no-wrap msgid "`{beech}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1101 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1104 #, no-wrap msgid "`{roberto}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1104 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1107 #, no-wrap msgid "`{rodrigc}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1107 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1110 #, no-wrap msgid "`{ler}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1110 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1113 #, no-wrap msgid "`{leres}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1113 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1116 #, no-wrap msgid "`{robak}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1116 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1119 #, no-wrap msgid "`{guido}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1119 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1122 #, no-wrap msgid "`{rea}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1122 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1125 #, no-wrap msgid "`{ray}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1125 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1128 #, no-wrap msgid "`{niklas}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1128 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1131 #, no-wrap msgid "`{salvadore}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1131 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1134 #, no-wrap msgid "`{bsam}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1134 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1137 #, no-wrap msgid "`{marks}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1137 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1140 #, no-wrap msgid "`{bschmidt}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1140 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1143 #, no-wrap msgid "`{wosch}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1143 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1146 #, no-wrap msgid "`{cy}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1146 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1149 #, no-wrap msgid "`{das}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1149 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1152 #, no-wrap msgid "`{scheidell}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1152 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1155 #, no-wrap msgid "`{matthew}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1155 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1158 #, no-wrap msgid "`{tmseck}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1158 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1161 #, no-wrap msgid "`{johans}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1161 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1164 #, no-wrap msgid "`{bakul}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1164 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1167 #, no-wrap msgid "`{gshapiro}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1167 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1170 #, no-wrap msgid "`{wxs}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1170 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1173 #, no-wrap msgid "`{nork}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1173 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1176 #, no-wrap msgid "`{syrinx}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1176 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1179 #, no-wrap msgid "`{vanilla}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1179 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1182 #, no-wrap msgid "`{ashish}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1182 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1185 #, no-wrap msgid "`{asiciliano}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1185 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1188 #, no-wrap msgid "`{chs}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1188 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1191 #, no-wrap msgid "`{bms}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1191 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1194 #, no-wrap msgid "`{demon}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1194 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1197 #, no-wrap msgid "`{jesper}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1197 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1200 #, no-wrap msgid "`{scop}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1200 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1203 #, no-wrap msgid "`{anray}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1203 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1206 #, no-wrap msgid "`{flo}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1206 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1209 #, no-wrap msgid "`{glebius}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1209 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1212 #, no-wrap msgid "`{kensmith}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1212 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1215 #, no-wrap msgid "`{ben}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1215 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1218 #, no-wrap msgid "`{des}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1218 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1221 #, no-wrap msgid "`{sobomax}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1221 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1224 #, no-wrap msgid "`{asomers}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1224 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1227 #, no-wrap msgid "`{brian}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1227 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1230 #, no-wrap msgid "`{sson}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1230 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1233 #, no-wrap msgid "`{nsouch}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1233 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1236 #, no-wrap msgid "`{ssouhlal}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1236 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1239 #, no-wrap msgid "`{loos}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1239 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1242 #, no-wrap msgid "`{brnrd}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1242 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1245 #, no-wrap msgid "`{rink}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1245 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1248 #, no-wrap msgid "`{vsevolod}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1248 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1251 #, no-wrap msgid "`{pstef}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1251 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1254 #, no-wrap msgid "`{zi}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1254 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1257 #, no-wrap msgid "`{lstewart}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1257 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1260 #, no-wrap msgid "`{murray}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1260 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1263 #, no-wrap msgid "`{vs}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1263 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1266 #, no-wrap msgid "`{xride}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1266 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1269 #, no-wrap msgid "`{marius}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1269 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1272 #, no-wrap msgid "`{cs}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1272 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1275 #, no-wrap msgid "`{clsung}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1275 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1278 #, no-wrap msgid "`{gsutter}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1278 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1281 #, no-wrap msgid "`{metal}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1281 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1284 #, no-wrap msgid "`{ryusuke}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1284 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1287 #, no-wrap msgid "`{nyan}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1287 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1290 #, no-wrap msgid "`{sahil}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1290 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1293 #, no-wrap msgid "`{tota}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1293 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1296 #, no-wrap msgid "`{romain}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1296 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1299 #, no-wrap msgid "`{eduardo}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1299 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1302 #, no-wrap msgid "`{sylvio}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1302 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1305 #, no-wrap msgid "`{itetcu}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1305 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1308 #, no-wrap msgid "`{mi}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1308 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1311 #, no-wrap msgid "`{gordon}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1311 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1314 #, no-wrap msgid "`{lth}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1314 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1317 #, no-wrap msgid "`{fabient}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1317 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1320 #, no-wrap msgid "`{thierry}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1320 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1323 #, no-wrap msgid "`{thompsa}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1323 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1326 #, no-wrap msgid "`{flz}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1326 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1329 #, no-wrap msgid "`{jilles}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1329 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1332 #, no-wrap msgid "`{ganbold}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1332 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1335 #, no-wrap msgid "`{tuexen}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1335 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1338 #, no-wrap msgid "`{gonzo}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1338 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1341 #, no-wrap msgid "`{ume}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1341 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1344 #, no-wrap msgid "`{ups}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1344 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1347 #, no-wrap msgid "`{fsu}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1347 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1350 #, no-wrap msgid "`{mikael}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1353 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1356 #, no-wrap msgid "`{ram}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1356 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1359 #, no-wrap msgid "`{bryanv}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1359 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1362 #, no-wrap msgid "`{nectar}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1362 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1365 #, no-wrap msgid "`{avilla}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1365 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1368 #, no-wrap msgid "`{nivit}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1368 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1371 #, no-wrap msgid "`{ivoras}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1371 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1374 #, no-wrap msgid "`{stefan}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1374 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1377 #, no-wrap msgid "`{kaiw}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1377 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1380 #, no-wrap msgid "`{adamw}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1380 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1383 #, no-wrap msgid "`{naddy}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1383 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1386 #, no-wrap msgid "`{peter}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1386 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1389 #, no-wrap msgid "`{nwhitehorn}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1389 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1392 #, no-wrap msgid "`{miwi}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1392 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1395 #, no-wrap msgid "`{nate}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1395 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1398 #, no-wrap msgid "`{twinterg}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1398 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1401 #, no-wrap msgid "`{def}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1401 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1404 #, no-wrap msgid "`{wollman}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1404 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1407 #, no-wrap msgid "`{joerg}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1407 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1410 #, no-wrap msgid "`{ygy}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1410 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1413 #, no-wrap msgid "`{emax}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1413 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1416 #, no-wrap msgid "`{oshogbo}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1416 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1419 #, no-wrap msgid "`{riggs}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1419 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1422 #, no-wrap msgid "`{egypcio}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1422 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1425 #, no-wrap msgid "`{bz}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1425 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1428 #, no-wrap msgid "`{dsl}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1428 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1431 #, no-wrap msgid "`{zeising}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1431 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1434 #, no-wrap msgid "`{phantom}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1434 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1437 #, no-wrap msgid "`{tz}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1437 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1440 #, no-wrap msgid "`{rigoletto}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1440 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1443 #, no-wrap msgid "`{kaktus}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1443 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1446 #, no-wrap msgid "`{samm}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1446 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1449 #, no-wrap msgid "`{arrowd}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1449 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1452 #, no-wrap msgid "`{ronald}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1452 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1455 #, no-wrap msgid "`{meta}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1455 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1458 #, no-wrap msgid "`{rnagy}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1458 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1461 #, no-wrap msgid "`{vvd}`" msgstr "" #. type: Title == -#: documentation/content/en/articles/pgpkeys/_index.adoc:1462 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1465 #, no-wrap msgid "Other Cluster Account Holders" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1464 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1467 #, no-wrap msgid "`{bk}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1467 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1470 #, no-wrap msgid "`{deb}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1470 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1473 #, no-wrap msgid "`{debdrup}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1473 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1476 #, no-wrap msgid "`{dutchdaemon}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1476 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1479 #, no-wrap msgid "`{keymaster}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1479 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1482 #, no-wrap msgid "`{mwlucas}`" msgstr "" #. type: Title === -#: documentation/content/en/articles/pgpkeys/_index.adoc:1482 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1485 #, no-wrap msgid "`{dhw}`" msgstr "" diff --git a/documentation/content/en/books/developers-handbook/introduction/_index.po b/documentation/content/en/books/developers-handbook/introduction/_index.po index 2ff0c70cfa..a489b85abe 100644 --- a/documentation/content/en/books/developers-handbook/introduction/_index.po +++ b/documentation/content/en/books/developers-handbook/introduction/_index.po @@ -1,403 +1,153 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2022-02-01 10:28-0300\n" +"POT-Creation-Date: 2023-06-19 21:08-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/developers-handbook/introduction/_index.adoc:1 #, no-wrap msgid "Introduction to the FreeBSD Developers Handbook" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:1 #, no-wrap msgid "Chapter 1. Introduction" msgstr "" #. type: Title = #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:16 #, no-wrap msgid "Introduction" msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:54 #, no-wrap msgid "Developing on FreeBSD" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:59 msgid "" "So here we are. System all installed and you are ready to start " "programming. But where to start? What does FreeBSD provide? What can it do " "for me, as a programmer?" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:65 msgid "" "These are some questions which this chapter tries to answer. Of course, " "programming has different levels of proficiency like any other trade. For " "some it is a hobby, for others it is their profession. The information in " "this chapter might be aimed toward the beginning programmer; indeed, it " "could serve useful for the programmer unfamiliar with the FreeBSD platform." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:67 #, no-wrap msgid "The BSD Vision" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:70 msgid "" "To produce the best UNIX(R) like operating system package possible, with due " "respect to the original software tools ideology as well as usability, " "performance and stability." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:72 #, no-wrap msgid "Architectural Guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:75 msgid "Our ideology can be described by the following guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:77 msgid "" "Do not add new functionality unless an implementor cannot complete a real " "application without it." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:78 msgid "" "It is as important to decide what a system is not as to decide what it is. " "Do not serve all the world's needs; rather, make the system extensible so " "that additional needs can be met in an upwardly compatible fashion." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:79 msgid "" "The only thing worse than generalizing from one example is generalizing from " "no examples at all." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:80 msgid "" "If a problem is not completely understood, it is probably best to provide no " "solution at all." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:81 msgid "" "If you can get 90 percent of the desired effect for 10 percent of the work, " "use the simpler solution." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:82 msgid "Isolate complexity as much as possible." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:83 msgid "" "Provide mechanism, rather than policy. In particular, place user interface " "policy in the client's hands." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:85 msgid "From Scheifler & Gettys: \"X Window System\"" msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:87 #, no-wrap msgid "The Layout of /usr/src" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/introduction/_index.adoc:91 msgid "" -"The complete source code to FreeBSD is available from our public " -"repository. The source code is normally installed in [.filename]#/usr/src# " -"which contains the following subdirectories:" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:96 -#, no-wrap -msgid "Directory" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:98 -#, no-wrap -msgid "Description" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:99 -#, no-wrap -msgid "[.filename]#bin/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:101 -#, no-wrap -msgid "Source for files in [.filename]#/bin#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:102 -#, no-wrap -msgid "[.filename]#cddl/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:104 -#, no-wrap -msgid "Utilities covered by the Common Development and Distribution License" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:105 -#, no-wrap -msgid "[.filename]#contrib/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:107 -#, no-wrap -msgid "Source for files from contributed software" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:108 -#, no-wrap -msgid "[.filename]#crypto/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:110 -#, no-wrap -msgid "Cryptographical sources" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:111 -#, no-wrap -msgid "[.filename]#etc/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:113 -#, no-wrap -msgid "Source for files in [.filename]#/etc#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:114 -#, no-wrap -msgid "[.filename]#gnu/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:116 -#, no-wrap -msgid "Utilities covered by the GNU Public License" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:117 -#, no-wrap -msgid "[.filename]#include/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:119 -#, no-wrap -msgid "Source for files in [.filename]#/usr/include#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:120 -#, no-wrap -msgid "[.filename]#kerberos5/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:122 -#, no-wrap -msgid "Source for Kerberos version 5" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:123 -#, no-wrap -msgid "[.filename]#lib/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:125 -#, no-wrap -msgid "Source for files in [.filename]#/usr/lib#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:126 -#, no-wrap -msgid "[.filename]#libexec/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:128 -#, no-wrap -msgid "Source for files in [.filename]#/usr/libexec#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:129 -#, no-wrap -msgid "[.filename]#release/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:131 -#, no-wrap -msgid "Files required to produce a FreeBSD release" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:132 -#, no-wrap -msgid "[.filename]#rescue/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:134 -#, no-wrap -msgid "Build system for the [.filename]#/rescue# utilities" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:135 -#, no-wrap -msgid "[.filename]#sbin/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:137 -#, no-wrap -msgid "Source for files in [.filename]#/sbin#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:138 -#, no-wrap -msgid "[.filename]#secure/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:140 -#, no-wrap -msgid "Contributed cryptographic sources" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:141 -#, no-wrap -msgid "[.filename]#share/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:143 -#, no-wrap -msgid "Source for files in [.filename]#/usr/share#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:144 -#, no-wrap -msgid "[.filename]#sys/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:146 -#, no-wrap -msgid "Kernel source files" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:147 -#, no-wrap -msgid "[.filename]#tests/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:149 -#, no-wrap -msgid "The FreeBSD test suite" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:150 -#, no-wrap -msgid "[.filename]#tools/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:152 -#, no-wrap -msgid "Tools used for maintenance and testing of FreeBSD" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:153 -#, no-wrap -msgid "[.filename]#usr.bin/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:155 -#, no-wrap -msgid "Source for files in [.filename]#/usr/bin#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:156 -#, no-wrap -msgid "[.filename]#usr.sbin/#" -msgstr "" - -#. type: Table -#: documentation/content/en/books/developers-handbook/introduction/_index.adoc:157 -#, no-wrap -msgid "Source for files in [.filename]#/usr/sbin#" +"The complete source code for FreeBSD is available from our link:https://cgit." +"freebsd.org/src/[public Git repository]. The source code is normally " +"installed in [.filename]#/usr/src#. The layout of the source tree is " +"described by the top-level link:https://cgit.freebsd.org/src/tree/README." +"md[README.md] file." msgstr "" diff --git a/documentation/content/en/books/faq/_index.po b/documentation/content/en/books/faq/_index.po index a1a2dcc79c..f3d4df90d2 100644 --- a/documentation/content/en/books/faq/_index.po +++ b/documentation/content/en/books/faq/_index.po @@ -1,7249 +1,7242 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-04-20 20:56-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/faq/_index.adoc:1 #, no-wrap msgid "Frequently Asked Questions, and answers, covering all aspects of FreeBSD" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/faq/_index.adoc:1 #, no-wrap msgid "Frequently Asked Questions for FreeBSD 12.X and 13.X" msgstr "" #. type: Title = #: documentation/content/en/books/faq/_index.adoc:13 #, no-wrap msgid "Frequently Asked Questions for FreeBSD {rel2-relx} and {rel-relx}" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:58 msgid "Abstract" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:61 msgid "" "This is the Frequently Asked Questions (FAQ) for FreeBSD versions {rel-relx} " "and {rel2-relx}. Every effort has been made to make this FAQ as informative " "as possible; if you have any suggestions as to how it may be improved, send " "them to the {freebsd-doc}." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:64 msgid "" "The latest version of this document is always available from the extref:{faq}" "[FreeBSD website]. It may also be downloaded as one large link:.[HTML] file " "with HTTP or as a variety of other formats from the https://download.freebsd." "org/doc/[FreeBSD FTP server]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:66 msgid "'''" msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:70 #, no-wrap msgid "Introduction" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:73 #, no-wrap msgid "What is FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:76 msgid "" "FreeBSD is a modern operating system for desktops, laptops, servers, and " "embedded systems with support for a large number of https://www.FreeBSD.org/" "platforms/[platforms]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:79 msgid "" "It is based on U.C. Berkeley's \"4.4BSD-Lite\" release, with some \"4.4BSD-" "Lite2\" enhancements. It is also based indirectly on William Jolitz's port " "of U.C. Berkeley's \"Net/2\" to the i386(TM), known as \"386BSD\", though " "very little of the 386BSD code remains." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:81 msgid "" "FreeBSD is used by companies, Internet Service Providers, researchers, " "computer professionals, students and home users all over the world in their " "work, education and recreation." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:83 msgid "" "For more detailed information on FreeBSD, refer to the extref:{handbook}" "[FreeBSD Handbook]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:85 #, no-wrap msgid "What is the goal of the FreeBSD Project?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:88 msgid "" "The goal of the FreeBSD Project is to provide a stable and fast general " "purpose operating system that may be used for any purpose without strings " "attached." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:90 #, no-wrap msgid "Does the FreeBSD license have any restrictions?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:95 msgid "" "Yes. Those restrictions do not control how the code is used, but how to " "treat the FreeBSD Project itself. The license itself is available at " "https://www.FreeBSD.org/copyright/freebsd-license/[license] and can be " "summarized like this:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:97 msgid "Do not claim that you wrote this." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:98 msgid "Do not sue us if it breaks." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:99 msgid "Do not remove or modify the license." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:103 msgid "" "Many of us have a significant investment in the project and would certainly " "not mind a little financial compensation now and then, but we definitely do " "not insist on it. We believe that our first and foremost \"mission\" is to " "provide code to any and all comers, and for whatever purpose, so that the " "code gets the widest possible use and provides the widest possible benefit. " "This, we believe, is one of the most fundamental goals of Free Software and " "one that we enthusiastically support." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:106 msgid "" "Code in our source tree which falls under the https://www.FreeBSD.org/" "copyright/COPYING[GNU General Public License (GPL)] or https://www.FreeBSD." "org/copyright/COPYING.LIB[GNU Library General Public License (LGPL)] comes " "with slightly more strings attached, though at least on the side of enforced " "access rather than the usual opposite. Due to the additional complexities " "that can evolve in the commercial use of GPL software, we do, however, " "endeavor to replace such software with submissions under the more relaxed " "https://www.FreeBSD.org/copyright/freebsd-license/[FreeBSD license] whenever " "possible." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:108 #, no-wrap msgid "Can FreeBSD replace my current operating system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:112 msgid "" "For most people, yes. But this question is not quite that cut-and-dried." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:119 msgid "" "Most people do not actually use an operating system. They use " "applications. The applications are what really use the operating system. " "FreeBSD is designed to provide a robust and full-featured environment for " "applications. It supports a wide variety of web browsers, office suites, " "email readers, graphics programs, programming environments, network servers, " "and much more. Most of these applications can be managed through the " "https://www.FreeBSD.org/ports/[Ports Collection]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:124 msgid "" "If an application is only available on one operating system, that operating " "system cannot just be replaced. Chances are, there is a very similar " "application on FreeBSD, however. As a solid office or Internet server or a " "reliable workstation, FreeBSD will almost certainly do everything you need. " "Many computer users across the world, including both novices and experienced " "UNIX(R) administrators, use FreeBSD as their only desktop operating system." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:129 msgid "" "Users migrating to FreeBSD from another UNIX(R)-like environment will find " "FreeBSD to be similar. Windows(R) and Mac OS(R) users may be interested in " "instead using https://www.ghostbsd.org/[GhostBSD], https://www.midnightbsd." "org/[MidnightBSD] or https://www.nomadbsd.org/[NomadBSD] three FreeBSD-based " "desktop distributions. Non-UNIX(R) users should expect to invest some " "additional time learning the UNIX(R) way of doing things. This FAQ and the " "extref:{handbook}[FreeBSD Handbook] are excellent places to start." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:131 #, no-wrap msgid "Why is it called FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:134 msgid "It may be used free of charge, even by commercial users." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:135 msgid "" "Full source for the operating system is freely available, and the minimum " "possible restrictions have been placed upon its use, distribution and " "incorporation into other work (commercial or non-commercial)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:136 msgid "" "Anyone who has an improvement or bug fix is free to submit their code and " "have it added to the source tree (subject to one or two obvious provisions)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:139 msgid "" "It is worth pointing out that the word \"free\" is being used in two ways " "here: one meaning \"at no cost\" and the other meaning \"do whatever you " "like\". Apart from one or two things you _cannot_ do with the FreeBSD code, " "for example pretending you wrote it, you can really do whatever you like " "with it." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:141 #, no-wrap msgid "What are the differences between FreeBSD and NetBSD, OpenBSD, and other open source BSD operating systems?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:145 msgid "" "James Howard wrote a good explanation of the history and differences between " "the various projects, called https://jameshoward.us/archive/bsd-family-tree/" "[The BSD Family Tree] which goes a fair way to answering this question. " "Some of the information is out of date, but the history portion in " "particular remains accurate." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:148 msgid "" "Most of the BSDs share patches and code, even today. All of the BSDs have " "common ancestry." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:151 msgid "" "The design goals of FreeBSD are described in <>, above. The " "design goals of the other most popular BSDs may be summarized as follows:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:154 msgid "" "OpenBSD aims for operating system security above all else. The OpenBSD team " "wrote man:ssh[1] and man:pf[4], which have both been ported to FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:155 msgid "NetBSD aims to be easily ported to other hardware platforms." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:156 msgid "" "DragonFly BSD is a fork of FreeBSD 4.8 that has since developed many " "interesting features of its own, including the HAMMER file system and " "support for user-mode \"vkernels\"." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:158 #, no-wrap msgid "What is the latest version of FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:162 msgid "" "At any point in the development of FreeBSD, there can be multiple parallel " "branches. {rel-relx} releases are made from the {rel-stable} branch, and " "{rel2-relx} releases are made from the {rel2-stable} branch." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:165 msgid "" "Up until the release of 12.0, the {rel2-relx} series was the one known as _-" "STABLE_. However, as of {rel-head-relx}, the {rel2-relx} branch will be " "designated for an \"extended support\" status and receive only fixes for " "major problems, such as security-related fixes." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:168 msgid "" "Releases are made <>. While many people stay " "more up-to-date with the FreeBSD sources (see the questions on <> and <>) than that, doing so is more " "of a commitment, as the sources are a moving target." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:170 msgid "" "More information on FreeBSD releases can be found on the https://www.FreeBSD." "org/releng/#release-build[Release Engineering page] and in man:release[7]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:172 #, no-wrap msgid "What is _FreeBSD-CURRENT_?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:177 msgid "" "extref:{handbook}cutting-edge/[FreeBSD-CURRENT, current] is the development " "version of the operating system, which will in due course become the new " "FreeBSD-STABLE branch. As such, it is really only of interest to developers " "working on the system and die-hard hobbyists. See the extref:{handbook}" "cutting-edge/[relevant section, current] in the extref:{handbook}[Handbook] " "for details on running _-CURRENT_." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:181 msgid "" "Users not familiar with FreeBSD should not use FreeBSD-CURRENT. This branch " "sometimes evolves quite quickly and due to mistakes can be un-buildable at " "times. People that use FreeBSD-CURRENT are expected to be able to analyze, " "debug, and report problems." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:183 #, no-wrap msgid "What is the FreeBSD-STABLE concept?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:190 msgid "" "_FreeBSD-STABLE_ is the development branch from which major releases are " "made. Changes go into this branch at a slower pace and with the general " "assumption that they have first been tested in FreeBSD-CURRENT. However, at " "any given time, the sources for FreeBSD-STABLE may or may not be suitable " "for general use, as it may uncover bugs and corner cases that were not yet " "found in FreeBSD-CURRENT. Users who do not have the resources to perform " "testing should instead run the most recent release of FreeBSD. _FreeBSD-" "CURRENT_, on the other hand, has been one unbroken line since 2.0 was " "released." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:192 msgid "" "For more detailed information on branches see \"extref:{releng}[FreeBSD " "Release Engineering: Creating the Release Branch, rel-branch]\", the status " "of the branches and the upcoming release schedule can be found on the " "https://www.FreeBSD.org/releng[Release Engineering Information] page." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:195 msgid "" "Version {u-rel123-announce}[{rel123-current}] is the latest release from the " "{rel2-stable} branch; it was released on {rel123-current-date}. Version {u-" "rel131-announce}[{rel131-current}] is the latest release from the {rel-" "stable} branch; it was released on {rel131-current-date}." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:197 #, no-wrap msgid "When are FreeBSD releases made?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:203 msgid "" "The {re} releases a new major version of FreeBSD about every 18 months and a " "new minor version about every 8 months, on average. Release dates are " "announced well in advance, so that the people working on the system know " "when their projects need to be finished and tested. A testing period " "precedes each release, to ensure that the addition of new features does not " "compromise the stability of the release. Many users regard this caution as " "one of the best things about FreeBSD, even though waiting for all the latest " "goodies to reach _-STABLE_ can be a little frustrating." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:205 msgid "" "More information on the release engineering process (including a schedule of " "upcoming releases) can be found on the https://www.FreeBSD.org/releng/" "[release engineering] pages on the FreeBSD Web site." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:207 msgid "" "For people who need or want a little more excitement, binary snapshots are " "made weekly as discussed above." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:209 #, no-wrap msgid "When are FreeBSD snapshots made?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:213 msgid "" "FreeBSD link:https://www.FreeBSD.org/snapshots/[snapshot] releases are made " "based on the current state of the _-CURRENT_ and _-STABLE_ branches. The " "goals behind each snapshot release are:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:215 msgid "To test the latest version of the installation software." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:216 msgid "" "To give people who would like to run _-CURRENT_ or _-STABLE_ but who do not " "have the time or bandwidth to follow it on a day-to-day basis an easy way of " "bootstrapping it onto their systems." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:218 msgid "" "To preserve a fixed reference point for the code in question, just in case " -"we break something really badly later. (Although Subversion normally " -"prevents anything horrible like this happening.)" +"we break something really badly later. (Although Git normally prevents " +"anything horrible like this happening.)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:219 msgid "" "To ensure that all new features and fixes in need of testing have the " "greatest possible number of potential testers." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:222 msgid "" "No claims are made that any _-CURRENT_ snapshot can be considered " "\"production quality\" for any purpose. If a stable and fully tested system " "is needed, stick to full releases." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:224 msgid "" "Snapshot releases are directly available from link:https://www.FreeBSD.org/" "snapshots/[snapshot]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:226 msgid "" "Official snapshots are generated on a regular basis for all actively " "developed branches." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:228 #, no-wrap msgid "Who is responsible for FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:232 msgid "" "The key decisions concerning the FreeBSD project, such as the overall " "direction of the project and who is allowed to add code to the source tree, " "are made by a link:https://www.FreeBSD.org/administration#t-core[core team] " "of 9 people. There is a much larger team of more than 350 extref:" "{contributors}[committers, staff-committers] who are authorized to make " "changes directly to the FreeBSD source tree." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:234 msgid "" "However, most non-trivial changes are discussed in advance in the <>, and there are no restrictions on who may take part in the " "discussion." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:236 #, no-wrap msgid "Where can I get FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:239 msgid "" "Every supported release of FreeBSD is available from the https://www.freebsd." "org/where/[FreeBSD release locator page]:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:241 msgid "" -"For the latest {rel-stable} release, {rel131-current}-RELEASE, follow the " -"link for link:https://www.freebsd.org/where/#download-rel131[the appropriate " -"architecture and installation mode for {rel131-current}-RELEASE]." +"For the latest {rel-stable} release, {rel132-current}-RELEASE, follow the " +"link for link:https://www.freebsd.org/where/#download-rel132[the appropriate " +"architecture and installation mode for {rel132-current}-RELEASE]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:242 msgid "" -"For the latest {rel2-stable} release, {rel123-current}-RELEASE, follow the " -"link for link:https://www.freebsd.org/where/#download-rel123[the appropriate " -"architecture and installation mode for {rel123-current}-RELEASE]." +"For the latest {rel2-stable} release, {rel124-current}-RELEASE, follow the " +"link for link:https://www.freebsd.org/where/#download-rel124[the appropriate " +"architecture and installation mode for {rel124-current}-RELEASE]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:243 msgid "" "link:https://www.FreeBSD.org/snapshots/[Snapshot] releases are made monthly " "for the <> and <> branches, these being of " "service purely to bleeding-edge testers and developers." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:245 msgid "" "Information about obtaining FreeBSD on CD, DVD, and other media can be found " "in extref:{handbook}mirrors/[the Handbook, mirrors]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:247 #, no-wrap msgid "How do I access the Problem Report database?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:250 msgid "" "The Problem Report database of all user change requests may be queried by " "using our web-based PR https://bugs.FreeBSD.org/search/[query] interface." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:252 msgid "" "The link:https://www.FreeBSD.org/support/bugreports[web-based problem report " "submission interface] can be used to submit problem reports through a web " "browser." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:254 msgid "" "Before submitting a problem report, read extref:{problem-reports}[Writing " "FreeBSD Problem Reports], an article on how to write good problem reports." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:256 #, no-wrap msgid "Documentation and Support" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:259 #, no-wrap msgid "What good books are there about FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:262 msgid "" "The project produces a wide range of documentation, available online from " "this link: https://www.FreeBSD.org/docs/[https://www.FreeBSD.org/docs/]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:264 #, no-wrap msgid "Is the documentation available in other formats, such as PDF?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:268 msgid "" "Yes. link:https://download.freebsd.org/doc/[The documentation is also " "available in several formats] on the FreeBSD download site." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:270 msgid "Documentation directories are categorized according to:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:272 msgid "The document's name, such as `faq`, or `handbook`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:274 msgid "" "The document's language, based on the locale names found under [.filename]#/" "usr/share/locale# on a FreeBSD system, with the encodings removed as all " "documentation now uses UTF-8. The current languages are:" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:279 #, no-wrap msgid "Name" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:281 #: documentation/content/en/books/faq/_index.adoc:357 #, no-wrap msgid "Meaning" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:282 #, no-wrap msgid "`en`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:284 #, no-wrap msgid "English" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:285 #, no-wrap msgid "`bn-bd`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:287 #, no-wrap msgid "Bengali or Bangla (Bangladesh)" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:288 #, no-wrap msgid "`da`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:290 #, no-wrap msgid "Danish" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:291 #, no-wrap msgid "`de`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:293 #, no-wrap msgid "German" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:294 #, no-wrap msgid "`el`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:296 #, no-wrap msgid "Greek" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:297 #, no-wrap msgid "`es`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:299 #, no-wrap msgid "Spanish" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:300 #, no-wrap msgid "`fr`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:302 #, no-wrap msgid "French" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:303 #, no-wrap msgid "`hu`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:305 #, no-wrap msgid "Hungarian" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:306 #, no-wrap msgid "`it`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:308 #, no-wrap msgid "Italian" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:309 #, no-wrap msgid "`ja`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:311 #, no-wrap msgid "Japanese" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:312 #, no-wrap msgid "`ko`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:314 #, no-wrap msgid "Korean" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:315 #, no-wrap msgid "`mn`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:317 #, no-wrap msgid "Mongolian" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:318 #, no-wrap msgid "`nl`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:320 #, no-wrap msgid "Dutch" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:321 #, no-wrap msgid "`pl`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:323 #, no-wrap msgid "Polish" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:324 #, no-wrap msgid "`pt-br`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:326 #, no-wrap msgid "Portuguese (Brazil)" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:327 #, no-wrap msgid "`ru`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:329 #, no-wrap msgid "Russian" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:330 #, no-wrap msgid "`tr`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:332 #, no-wrap msgid "Turkish" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:333 #, no-wrap msgid "`zh-cn`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:335 #, no-wrap msgid "Simplified Chinese (China)" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:336 #, no-wrap msgid "`zh-tw`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:337 #, no-wrap msgid "Traditional Chinese (Taiwan)" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:342 msgid "Some documents may not be available in all languages." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:350 msgid "" "The document's format. We produce the documentation in a number of " "different output formats. Each format has its own advantages and " "disadvantages. Some formats are better suited for online reading, while " "others are meant to be aesthetically pleasing when printed on paper. Having " "the documentation available in any of these formats ensures that our readers " "will be able to read the parts they are interested in, either on their " "monitor, or on paper after printing the documents. The currently available " "formats are:" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:355 #, no-wrap msgid "Format" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:358 #, no-wrap msgid "`html`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:360 #, no-wrap msgid "Depending on the document: one large HTML file containing the entire document or a collection of small linked HTML files, both together with images, stylesheets, and JavaScript" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:361 #, no-wrap msgid "`pdf`" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:362 #, no-wrap msgid "Adobe's Portable Document Format" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:364 #, no-wrap msgid "The compression and packaging scheme.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:366 #, no-wrap msgid "" "Where the format is `html`, the files are bundled up using man:tar[1].\n" "The resulting [.filename]#.tar# is then compressed using man:gzip[1].\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:368 #, no-wrap msgid "" "The PDF format generates one file.\n" "For example, [.filename]#explaining-bsd_en.pdf#, [.filename]#faq_en.pdf#, and so on.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:370 msgid "" "After choosing the format, download the files, uncompress them if necessary, " "then copy the appropriate documents into place." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:372 msgid "" "For example, the HTML version of the FAQ can be found in [.filename]#doc/en/" "books/faq/faq_en.tar.gz# To download and uncompress that file, type:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:377 #, no-wrap msgid "" "% fetch https://download.freebsd.org/doc/en/books/faq/faq_en.tar.gz\n" "% tar xvf faq_en.tar.gz\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:381 msgid "" "If the file is compressed, tar will automatically detect the appropriate " "format and decompress it correctly, resulting in a collection of files. The " "main one is called [.filename]#index.html#, which will contain the whole " "document, starting with the table of contents linking to the other parts of " "the document." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:383 #, no-wrap msgid "Where do I find info on the FreeBSD mailing lists? What FreeBSD news groups are available?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:386 msgid "" "Refer to the extref:{handbook}eresources/[Handbook entry on mailing-lists, " "eresources-mail] and the extref:{handbook}eresources/[Handbook entry on " "newsgroups, eresources-news]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:388 #, no-wrap msgid "Are there FreeBSD IRC (Internet Relay Chat) channels?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:391 msgid "" "Yes, most major IRC networks host a FreeBSD chat channel and the FreeBSD " "wiki holds an up to date https://wiki.freebsd.org/IRC/Channels[list of IRC " "channels]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:394 msgid "" "Each of these channels are distinct and are not connected to each other. " "Since their chat styles differ, try each to find one suited to your chat " "style." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:396 #, no-wrap msgid "Are there any web based forums to discuss FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:399 msgid "" "The official FreeBSD forums are located at https://forums.FreeBSD.org/" "[https://forums.FreeBSD.org/]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:401 #, no-wrap msgid "Where can I get commercial FreeBSD training and support?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:404 msgid "" "http://www.ixsystems.com[iXsystems, Inc.], parent company of the http://www." "freebsdmall.com/[FreeBSD Mall], provides commercial FreeBSD and TrueOS " "software http://www.ixsystems.com/support[support], in addition to FreeBSD " "development and tuning solutions." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:407 msgid "" "BSD Certification Group, Inc. provides system administration certifications " "for DragonFly BSD, FreeBSD, NetBSD, and OpenBSD. Refer to http://www." "BSDCertification.org[their site] for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:409 msgid "" "Any other organizations providing training and support should contact the " "Project to be listed here." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:411 #, no-wrap msgid "Installation" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:414 #, no-wrap msgid "Which platform should I download? I have a 64 bit capable Intel(R) CPU, but I only see amd64." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:420 msgid "" "amd64 is the term FreeBSD uses for 64-bit compatible x86 architectures (also " "known as \"x86-64\" or \"x64\"). Most modern computers should use amd64. " "Older hardware should use i386. When installing on a non-x86-compatible " "architecture, select the platform which best matches the hardware." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:422 #, no-wrap msgid "Which file do I download to get FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:425 msgid "" "On the https://www.freebsd.org/where/[Getting FreeBSD] page, select `[iso]` " "next to the architecture that matches the hardware." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:427 msgid "Any of the following can be used:" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:432 #, no-wrap msgid "file" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:434 #, no-wrap msgid "description" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:435 #, no-wrap msgid "[.filename]#disc1.iso#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:437 #, no-wrap msgid "Contains enough to install FreeBSD and a minimal set of packages." msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:438 #, no-wrap msgid "[.filename]#dvd1.iso#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:440 #, no-wrap msgid "Similar to [.filename]#disc1.iso# but with additional packages." msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:441 #, no-wrap msgid "[.filename]#memstick.img#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:443 #, no-wrap msgid "A bootable image sufficient for writing to a USB stick." msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:444 #, no-wrap msgid "[.filename]#bootonly.iso#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:445 #, no-wrap msgid "A minimal image that requires network access during installation to completely install FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:448 msgid "" "Full instructions on this procedure and a little bit more about installation " "issues in general can be found in the extref:{handbook}bsdinstall[Handbook " "entry on installing FreeBSD]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:450 #, no-wrap msgid "What do I do if the install image does not boot?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:453 msgid "" "This can be caused by not downloading the image in _binary_ mode when using " "FTP." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:457 msgid "" "Some FTP clients default their transfer mode to _ascii_ and attempt to " "change any end-of-line characters received to match the conventions used by " "the client's system. This will almost invariably corrupt the boot image. " "Check the SHA-256 checksum of the downloaded boot image: if it is not " "_exactly_ that on the server, then the download process is suspect." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:459 msgid "" "When using a command line FTP client, type _binary_ at the FTP command " "prompt after getting connected to the server and before starting the " "download of the image." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:461 #, no-wrap msgid "Where are the instructions for installing FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:464 msgid "" "Installation instructions can be found at extref:{handbook}bsdinstall/" "[Handbook entry on installing FreeBSD]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:466 #, no-wrap msgid "How can I make my own custom release or install disk?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:470 msgid "" "Customized FreeBSD installation media can be created by building a custom " "release. Follow the instructions in the extref:{releng}[Release " "Engineering] article." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:472 #, no-wrap msgid "Can Windows(R) co-exist with FreeBSD? (x86-specific)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:478 msgid "" "If Windows(R) is installed first, then yes. FreeBSD's boot manager will " "then manage to boot Windows(R) and FreeBSD. If Windows(R) is installed " "afterwards, it will overwrite the boot manager. If that happens, see the " "next section." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:480 #, no-wrap msgid "Another operating system destroyed my Boot Manager. How do I get it back? (x86-specific)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:485 msgid "" "This depends upon the boot manager. The FreeBSD boot selection menu can be " "reinstalled using man:boot0cfg[8]. For example, to restore the boot menu " "onto the disk _ada0_:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:489 #, no-wrap msgid "# boot0cfg -B ada0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:492 msgid "The non-interactive MBR bootloader can be installed using man:gpart[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:496 #, no-wrap msgid "# gpart bootcode -b /boot/mbr ada0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:499 msgid "For more complex situations, including GPT disks, see man:gpart[8]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:501 #, no-wrap msgid "Do I need to install the source?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:507 msgid "" "In general, no. There is nothing in the base system which requires the " "presence of the source to operate. Some ports, like package:sysutils/" "lsof[], will not build unless the source is installed. In particular, if " "the port builds a kernel module or directly operates on kernel structures, " "the source must be installed." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:509 #, no-wrap msgid "Do I need to build a kernel?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:515 msgid "" "Usually not. The supplied `GENERIC` kernel contains the drivers an ordinary " "computer will need. man:freebsd-update[8], the FreeBSD binary upgrade tool, " "cannot upgrade custom kernels, another reason to stick with the `GENERIC` " "kernel when possible. For computers with very limited RAM, such as embedded " "systems, it may be worthwhile to build a smaller custom kernel containing " "just the required drivers." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:517 #, no-wrap msgid "Should I use DES, Blowfish, or MD5 passwords and how do I specify which form my users receive?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:524 msgid "" "FreeBSD uses _SHA512_ by default. DES passwords are still available for " "backwards compatibility with operating systems that still use the less " "secure password format. FreeBSD also supports the Blowfish and MD5 password " "formats. Which password format to use for new passwords is controlled by " "the `passwd_format` login capability in [.filename]#/etc/login.conf#, which " "takes values of `des`, `blf` (if these are available) or `md5`. See the man:" "login.conf[5] manual page for more information about login capabilities." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:526 #, no-wrap msgid "What are the limits for FFS file systems?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:531 msgid "" "For FFS file systems, the largest file system is practically limited by the " "amount of memory required to man:fsck[8] the file system. man:fsck[8] " "requires one bit per fragment, which with the default fragment size of 4 KB " "equates to 32 MB of memory per TB of disk. This does mean that on " "architectures which limit userland processes to 2 GB (e.g., i386(TM)), the " "maximum man:fsck[8]'able filesystem is ~60 TB." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:533 msgid "" "If there was not a man:fsck[8] memory limit the maximum filesystem size " "would be 2 ^ 64 (blocks) * 32 KB => 16 Exa * 32 KB => 512 ZettaBytes." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:538 msgid "" "The maximum size of a single FFS file is approximately 2 PB with the default " "block size of 32 KB. Each 32 KB block can point to 4096 blocks. With " "triple indirect blocks, the calculation is 32 KB * 12 + 32 KB * 4096 + 32 KB " "* 4096^2 + 32 KB * 4096^3. Increasing the block size to 64 KB will increase " "the max file size by a factor of 16." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:540 #, no-wrap msgid "Why do I get an error message, readin failed after compiling and booting a new kernel?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:545 msgid "" "The world and kernel are out of sync. This is not supported. Be sure to " "use `make buildworld` and `make buildkernel` to update the kernel." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:547 msgid "" "Boot the system by specifying the kernel directly at the second stage, " "pressing any key when the `|` shows up before loader is started." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:549 #, no-wrap msgid "Is there a tool to perform post-installation configuration tasks?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:553 msgid "" "Yes. bsdconfig provides a nice interface to configure FreeBSD post-" "installation." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:555 #, no-wrap msgid "Hardware Compatibility" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:558 #, no-wrap msgid "General" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:561 #, no-wrap msgid "I want to get a piece of hardware for my FreeBSD system. Which model/brand/type is best?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:566 msgid "" "This is discussed continually on the FreeBSD mailing lists but is to be " "expected since hardware changes so quickly. Read through the Hardware Notes " "for FreeBSD link:{u-rel123-hardware}[{rel123-current}] or link:{u-rel131-" "hardware}[{rel131-current}] and search the https://www.FreeBSD.org/search/" "#mailinglists[mailing list archives] before asking about the latest and " "greatest hardware. Chances are a discussion about that type of hardware " "took place just last week." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:568 msgid "" "Before purchasing a laptop, check the archives for {freebsd-questions}, or " "possibly a specific mailing list for a particular hardware type." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:570 #, no-wrap msgid "What are the limits for memory?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:575 msgid "" "FreeBSD as an operating system generally supports as much physical memory " "(RAM) as the platform it is running on does. Keep in mind that different " "platforms have different limits for memory; for example i386(TM) without PAE " "supports at most 4 GB of memory (and usually less than that because of PCI " "address space) and i386(TM) with PAE supports at most 64 GB memory. As of " "FreeBSD 10, AMD64 platforms support up to 4 TB of physical memory." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:577 #, no-wrap msgid "Why does FreeBSD report less than 4 GB memory when installed on an i386(TM) machine?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:583 msgid "" "The total address space on i386(TM) machines is 32-bit, meaning that at most " "4 GB of memory is addressable (can be accessed). Furthermore, some " "addresses in this range are reserved by hardware for different purposes, for " "example for using and controlling PCI devices, for accessing video memory, " "and so on. Therefore, the total amount of memory usable by the operating " "system for its kernel and applications is limited to significantly less than " "4 GB. Usually, 3.2 GB to 3.7 GB is the maximum usable physical memory in " "this configuration." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:589 msgid "" "To access more than 3.2 GB to 3.7 GB of installed memory (meaning up to 4 GB " "but also more than 4 GB), a special tweak called PAE must be used. PAE " "stands for Physical Address Extension and is a way for 32-bit x86 CPUs to " "address more than 4 GB of memory. It remaps the memory that would otherwise " "be overlaid by address reservations for hardware devices above the 4 GB " "range and uses it as additional physical memory (see man:pae[4]). Using PAE " "has some drawbacks; this mode of memory access is a little bit slower than " "the normal (without PAE) mode and loadable modules (see man:kld[4]) are not " "supported. This means all drivers must be compiled into the kernel." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:594 msgid "" "The most common way to enable PAE is to build a new kernel with the special " "ready-provided kernel configuration file called [.filename]#PAE#, which is " "already configured to build a safe kernel. Note that some entries in this " "kernel configuration file are too conservative and some drivers marked as " "unready to be used with PAE are actually usable. A rule of thumb is that if " "the driver is usable on 64-bit architectures (like AMD64), it is also usable " "with PAE. When creating a custom kernel configuration file, PAE can be " "enabled by adding the following line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:598 #, no-wrap msgid "options PAE\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:603 msgid "" "PAE is not much used nowadays because most new x86 hardware also supports " "running in 64-bit mode, known as AMD64 or Intel(R) 64. It has a much larger " "address space and does not need such tweaks. FreeBSD supports AMD64 and it " "is recommended that this version of FreeBSD be used instead of the i386(TM) " "version if 4 GB or more memory is required." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:605 #, no-wrap msgid "Architectures and Processors" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:608 #, no-wrap msgid "Does FreeBSD support architectures other than the x86?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:615 msgid "" "Yes. FreeBSD divides support into multiple tiers. Tier 1 architectures, " "such as i386 or amd64; are fully supported. Tiers 2 and 3 are supported on " "a best-effort basis. A full explanation of the tier system is available in " "the extref:{committers-guide}[Committer's Guide., archs]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:617 msgid "" "A complete list of supported architectures can be found on the https://www." "FreeBSD.org/platforms/[platforms page.]" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:619 #, no-wrap msgid "Does FreeBSD support Symmetric Multiprocessing (SMP)?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:624 msgid "" "FreeBSD supports symmetric multi-processor (SMP) on all non-embedded " "platforms (e.g, i386, amd64, etc.). SMP is also supported in arm and MIPS " "kernels, although some CPUs may not support this. FreeBSD's SMP " "implementation uses fine-grained locking, and performance scales nearly " "linearly with number of CPUs." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:626 msgid "man:smp[4] has more details." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:628 #, no-wrap msgid "What is microcode? How do I install Intel(R) CPU microcode updates?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:632 msgid "" "Microcode is a method of programmatically implementing hardware level " "instructions. This allows for CPU bugs to be fixed without replacing the on " "board chip." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:634 msgid "Install package:sysutils/devcpu-data[], then add:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:638 #, no-wrap msgid "microcode_update_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:641 msgid "to [.filename]#/etc/rc.conf#" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:643 #, no-wrap msgid "Peripherals" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:646 #, no-wrap msgid "What kind of peripherals does FreeBSD support?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:649 msgid "" "See a list of hardware known to work and any applicable restrictions in the " "Hardware Notes for FreeBSD link:{u-rel123-hardware}[{rel123-current}] or " "link:{u-rel131-hardware}[{rel131-current}]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:651 #, no-wrap msgid "Keyboards and Mice" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:654 #, no-wrap msgid "Is it possible to use a mouse outside the X Window system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:658 msgid "" "The default console driver, man:vt[4], provides the ability to use a mouse " "pointer in text consoles to cut & paste text. Run the mouse daemon, man:" "moused[8], and turn on the mouse pointer in the virtual console:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:663 #, no-wrap msgid "" "# moused -p /dev/xxxx -t yyyy\n" "# vidcontrol -m on\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:669 msgid "" "Where _xxxx_ is the mouse device name and _yyyy_ is a protocol type for the " "mouse. The mouse daemon can automatically determine the protocol type of " "most mice, except old serial mice. Specify the `auto` protocol to invoke " "automatic detection. If automatic detection does not work, see the man:" "moused[8] manual page for a list of supported protocol types." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:672 msgid "" "For a PS/2 mouse, add `moused_enable=\"YES\"` to [.filename]#/etc/rc.conf# " "to start the mouse daemon at boot time. Additionally, to use the mouse " "daemon on all virtual terminals instead of just the console, add " "`allscreens_flags=\"-m on\"` to [.filename]#/etc/rc.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:675 msgid "" "When the mouse daemon is running, access to the mouse must be coordinated " "between the mouse daemon and other programs such as X Windows. Refer to the " "FAQ <> for more details on " "this issue." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:677 #, no-wrap msgid "How do I cut and paste text with a mouse in the text console?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:684 msgid "" "It is not possible to remove data using the mouse. However, it is possible " "to copy and paste. Once the mouse daemon is running as described in the " "<>, hold down button 1 (left button) and move the " "mouse to select a region of text. Then, press button 2 (middle button) to " "paste it at the text cursor. Pressing button 3 (right button) will " "\"extend\" the selected region of text." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:687 msgid "" "If the mouse does not have a middle button, it is possible to emulate one or " "remap buttons using mouse daemon options. See the man:moused[8] manual page " "for details." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:689 #, no-wrap msgid "My mouse has a fancy wheel and buttons. Can I use them in FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:695 msgid "" "The answer is, unfortunately, \"It depends\". These mice with additional " "features require specialized driver in most cases. Unless the mouse device " "driver or the user program has specific support for the mouse, it will act " "just like a standard two, or three button mouse." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:697 msgid "" "For the possible usage of wheels in the X Window environment, refer to <>." msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:699 #, no-wrap msgid "How do I use my delete key in sh and csh?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:703 msgid "" "For the Bourne Shell, add the following lines to [.filename]#~/.shrc#. See " "man:sh[1] and man:editrc[5]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:707 #, no-wrap msgid "bind ^[[3~ ed-delete-next-char # for xterm\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:711 msgid "" "For the C Shell, add the following lines to [.filename]#~/.cshrc#. See man:" "csh[1]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:715 #, no-wrap msgid "bindkey ^[[3~ delete-char # for xterm\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:718 #, no-wrap msgid "Other Hardware" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:721 #, no-wrap msgid "Workarounds for no sound from my man:pcm[4] sound card?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:725 msgid "" "Some sound cards set their output volume to 0 at every boot. On FreeBSD 13 " "and earlier, run the following command every time the machine boots:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:729 #, no-wrap msgid "# mixer pcm 100 vol 100 cd 100\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:732 msgid "Use the following command on FreeBSD 14 and later:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:736 #, no-wrap msgid "# mixer pcm.volume=100 vol.volume=100 cd.volume=100\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/faq/_index.adoc:739 #, no-wrap msgid "Does FreeBSD support power management on my laptop?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:743 msgid "" "FreeBSD supports the ACPI features found in modern hardware. Further " "information can be found in man:acpi[4]." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:745 #, no-wrap msgid "Troubleshooting" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:748 #, no-wrap msgid "Why is FreeBSD finding the wrong amount of memory on i386(TM) hardware?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:751 msgid "" "The most likely reason is the difference between physical memory addresses " "and virtual addresses." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:755 msgid "" "The convention for most PC hardware is to use the memory area between 3.5 GB " "and 4 GB for a special purpose (usually for PCI). This address space is " "used to access PCI hardware. As a result real, physical memory cannot be " "accessed by that address space." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:758 msgid "" "What happens to the memory that should appear in that location is hardware " "dependent. Unfortunately, some hardware does nothing and the ability to use " "that last 500 MB of RAM is entirely lost." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:761 msgid "" "Luckily, most hardware remaps the memory to a higher location so that it can " "still be used. However, this can cause some confusion when watching the " "boot messages." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:765 msgid "" "On a 32-bit version of FreeBSD, the memory appears lost, since it will be " "remapped above 4 GB, which a 32-bit kernel is unable to access. In this " "case, the solution is to build a PAE enabled kernel. See the entry on " "memory limits for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:769 msgid "" "On a 64-bit version of FreeBSD, or when running a PAE-enabled kernel, " "FreeBSD will correctly detect and remap the memory so it is usable. During " "boot, however, it may seem as if FreeBSD is detecting more memory than the " "system really has, due to the described remapping. This is normal and the " "available memory will be corrected as the boot process completes." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:771 #, no-wrap msgid "Why do my programs occasionally die with Signal 11 errors?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:775 msgid "" "Signal 11 errors are caused when a process has attempted to access memory " "which the operating system has not granted it access to. If something like " "this is happening at seemingly random intervals, start investigating the " "cause." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:777 msgid "These problems can usually be attributed to either:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:779 msgid "" "If the problem is occurring only in a specific custom application, it is " "probably a bug in the code." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:780 msgid "" "If it is a problem with part of the base FreeBSD system, it may also be " "buggy code, but more often than not these problems are found and fixed long " "before us general FAQ readers get to use these bits of code (that is what -" "CURRENT is for)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:782 msgid "" "It is probably not a FreeBSD bug if the problem occurs compiling a program, " "but the activity that the compiler is carrying out changes each time." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:786 msgid "" "For example, if `make buildworld` fails while trying to compile [." "filename]#ls.c# into [.filename]#ls.o# and, when run again, it fails in the " "same place, this is a broken build. Try updating source and try again. If " "the compile fails elsewhere, it is almost certainly due to hardware." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:788 msgid "" "In the first case, use a debugger such as man:gdb[1] to find the point in " "the program which is attempting to access a bogus address and fix it." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:790 msgid "In the second case, verify which piece of hardware is at fault." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:792 msgid "Common causes of this include:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:794 msgid "" "The hard disks might be overheating: Check that the fans are still working, " "as the disk and other hardware might be overheating." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:797 msgid "" "The processor running is overheating: This might be because the processor " "has been overclocked, or the fan on the processor might have died. In " "either case, ensure that the hardware is running at what it is specified to " "run at, at least while trying to solve this problem. If it is not, clock it " "back to the default settings.)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:800 msgid "" "Regarding overclocking, it is far cheaper to have a slow system than a fried " "system that needs replacing! Also the community is not sympathetic to " "problems on overclocked systems." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:801 msgid "" "Dodgy memory: if multiple memory SIMMS/DIMMS are installed, pull them all " "out and try running the machine with each SIMM or DIMM individually to " "narrow the problem down to either the problematic DIMM/SIMM or perhaps even " "a combination." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:804 msgid "" "Over-optimistic motherboard settings: the BIOS settings, and some " "motherboard jumpers, provide options to set various timings. The defaults " "are often sufficient, but sometimes setting the wait states on RAM too low, " "or setting the \"RAM Speed: Turbo\" option will cause strange behavior. A " "possible idea is to set to BIOS defaults, after noting the current settings " "first." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:808 msgid "" "Unclean or insufficient power to the motherboard. Remove any unused I/O " "boards, hard disks, or CD-ROMs, or disconnect the power cable from them, to " "see if the power supply can manage a smaller load. Or try another power " "supply, preferably one with a little more power. For instance, if the " "current power supply is rated at 250 Watts, try one rated at 300 Watts." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:811 msgid "" "Read the section on <> for a further explanation and a " "discussion on how memory testing software or hardware can still pass faulty " "memory. There is an extensive FAQ on this at http://www.bitwizard.nl/sig11/" "[the SIG11 problem FAQ]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:814 msgid "" "Finally, if none of this has helped, it is possibly a bug in FreeBSD. " "Follow <> to send a problem report." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:816 #, no-wrap msgid "My system crashes with either Fatal trap 12: page fault in kernel mode, or panic:, and spits out a bunch of information. What should I do?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:823 msgid "" "The FreeBSD developers are interested in these errors, but need more " "information than just the error message. Copy the full crash message. Then " "consult the FAQ section on <>, " "build a debugging kernel, and get a backtrace. This might sound difficult, " "but does not require any programming skills. Just follow the instructions." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:825 #, no-wrap msgid "What is the meaning of the error maxproc limit exceeded by uid %i, please see tuning(7) and login.conf(5)?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:832 msgid "" "The FreeBSD kernel will only allow a certain number of processes to exist at " "one time. The number is based on the `kern.maxusers` man:sysctl[8] " "variable. `kern.maxusers` also affects various other in-kernel limits, such " "as network buffers. If the machine is heavily loaded, increase `kern." "maxusers`. This will increase these other system limits in addition to the " "maximum number of processes." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:835 msgid "" "To adjust the `kern.maxusers` value, see the extref:{handbook}config/[File/" "Process Limits, kern-maxfiles] section of the Handbook. While that section " "refers to open files, the same limits apply to processes." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:841 msgid "" "If the machine is lightly loaded but running a very large number of " "processes, adjust the `kern.maxproc` tunable by defining it in [.filename]#/" "boot/loader.conf#. The tunable will not get adjusted until the system is " "rebooted. For more information about tuning tunables, see man:loader." "conf[5]. If these processes are being run by a single user, adjust `kern." "maxprocperuid` to be one less than the new `kern.maxproc` value. It must be " "at least one less because one system program, man:init[8], must always be " "running." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:843 #, no-wrap msgid "Why do full screen applications on remote machines misbehave?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:847 msgid "" "The remote machine may be setting the terminal type to something other than " "`xterm` which is required by the FreeBSD console. Alternatively the kernel " "may have the wrong values for the width and height of the terminal." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:850 msgid "" "Check the value of the `TERM` environment variable is `xterm`. If the " "remote machine does not support that try `vt100`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:853 msgid "" "Run `stty -a` to check what the kernel thinks the terminal dimensions are. " "If they are incorrect, they can be changed by running `stty rows _RR_ cols " "_CC_`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:855 msgid "" "Alternatively, if the client machine has package:x11/xterm[] installed, then " "running `resize` will query the terminal for the correct dimensions and set " "them." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:857 #, no-wrap msgid "Why does it take so long to connect to my computer via ssh or telnet?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:860 msgid "" "The symptom: there is a long delay between the time the TCP connection is " "established and the time when the client software asks for a password (or, " "in man:telnet[1]'s case, when a login prompt appears)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:863 msgid "" "The problem: more likely than not, the delay is caused by the server " "software trying to resolve the client's IP address into a hostname. Many " "servers, including the Telnet and SSH servers that come with FreeBSD, do " "this to store the hostname in a log file for future reference by the " "administrator." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:866 msgid "" "The remedy: if the problem occurs whenever connecting the client computer to " "any server, the problem is with the client. If the problem only occurs when " "someone connects to the server computer, the problem is with the server." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:870 msgid "" "If the problem is with the client, the only remedy is to fix the DNS so the " "server can resolve it. If this is on a local network, consider it a server " "problem and keep reading. If this is on the Internet, contact your ISP." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:876 msgid "" "If the problem is with the server on a local network, configure the server " "to resolve address-to-hostname queries for the local address range. See man:" "hosts[5] and man:named[8] for more information. If this is on the Internet, " "the problem may be that the local server's resolver is not functioning " "correctly. To check, try to look up another host such as `www.yahoo.com`. " "If it does not work, that is the problem." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:880 msgid "" "Following a fresh install of FreeBSD, it is also possible that domain and " "name server information is missing from [.filename]#/etc/resolv.conf#. This " "will often cause a delay in SSH, as the option `UseDNS` is set to `yes` by " "default in [.filename]#/etc/ssh/sshd_config#. If this is causing the " "problem, either fill in the missing information in [.filename]#/etc/resolv." "conf# or set `UseDNS` to `no` in [.filename]#sshd_config# as a temporary " "workaround." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:882 #, no-wrap msgid "Why does file: table is full show up repeatedly in man:dmesg[8]?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:886 msgid "" "This error message indicates that the number of available file descriptors " "have been exhausted on the system. Refer to the extref:{handbook}config/" "[kern.maxfiles, kern-maxfiles] section of the extref:{handbook}config/" "[Tuning Kernel Limits, configtuning-kernel-limits] section of the Handbook " "for a discussion and solution." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:888 #, no-wrap msgid "Why does the clock on my computer keep incorrect time?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:891 msgid "" "The computer has two or more clocks, and FreeBSD has chosen to use the wrong " "one." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:894 msgid "" "Run man:dmesg[8], and check for lines that contain `Timecounter`. The one " "with the highest quality value that FreeBSD chose." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:902 #, no-wrap msgid "" "# dmesg | grep Timecounter\n" "Timecounter \"i8254\" frequency 1193182 Hz quality 0\n" "Timecounter \"ACPI-fast\" frequency 3579545 Hz quality 1000\n" "Timecounter \"TSC\" frequency 2998570050 Hz quality 800\n" "Timecounters tick every 1.000 msec\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:905 msgid "Confirm this by checking the `kern.timecounter.hardware` man:sysctl[3]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:910 #, no-wrap msgid "" "# sysctl kern.timecounter.hardware\n" "kern.timecounter.hardware: ACPI-fast\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:914 msgid "" "It may be a broken ACPI timer. The simplest solution is to disable the ACPI " "timer in [.filename]#/boot/loader.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:918 #, no-wrap msgid "debug.acpi.disabled=\"timer\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:921 msgid "" "Or the BIOS may modify the TSC clock-perhaps to change the speed of the " "processor when running from batteries, or going into a power saving mode, " "but FreeBSD is unaware of these adjustments, and appears to gain or lose " "time." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:923 msgid "" "In this example, the `i8254` clock is also available, and can be selected by " "writing its name to the `kern.timecounter.hardware` man:sysctl[3]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:928 #, no-wrap msgid "" "# sysctl kern.timecounter.hardware=i8254\n" "kern.timecounter.hardware: TSC -> i8254\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:931 msgid "The computer should now start keeping more accurate time." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:933 msgid "" "To have this change automatically run at boot time, add the following line " "to [.filename]#/etc/sysctl.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:937 #, no-wrap msgid "kern.timecounter.hardware=i8254\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:940 #, no-wrap msgid "What does the error swap_pager: indefinite wait buffer: mean?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:946 msgid "" "This means that a process is trying to page memory from disk, and the page " "attempt has hung trying to access the disk for more than 20 seconds. It " "might be caused by bad blocks on the disk drive, disk wiring, cables, or any " "other disk I/O-related hardware. If the drive itself is bad, disk errors " "will appear in [.filename]#/var/log/messages# and in the output of `dmesg`. " "Otherwise, check the cables and connections." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:948 #, no-wrap msgid "What is a lock order reversal?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:953 msgid "" "The FreeBSD kernel uses a number of resource locks to arbitrate contention " "for certain resources. When multiple kernel threads try to obtain multiple " "resource locks, there's always the potential for a deadlock, where two " "threads have each obtained one of the locks and blocks forever waiting for " "the other thread to release one of the other locks. This sort of locking " "problem can be avoided if all threads obtain the locks in the same order." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:956 msgid "" "A run-time lock diagnostic system called man:witness[4], enabled in FreeBSD-" "CURRENT and disabled by default for stable branches and releases, detects " "the potential for deadlocks due to locking errors, including errors caused " "by obtaining multiple resource locks with a different order from different " "parts of the kernel. The man:witness[4] framework tries to detect this " "problem as it happens, and reports it by printing a message to the system " "console about a `lock order reversal` (often referred to also as LOR)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:959 msgid "" "It is possible to get false positives, as man:witness[4] is conservative. A " "true positive report _does not_ mean that a system is dead-locked; instead " "it should be understood as a warning that a deadlock could have happened " "here." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:963 msgid "" "Problematic LORs tend to get fixed quickly, so check the {freebsd-current} " "before posting to it." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:966 #, no-wrap msgid "What does 'Called ... with the following non-sleepable locks held' mean?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:969 msgid "" "This means that a function that may sleep was called while a mutex (or other " "unsleepable) lock was held." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:974 msgid "" "The reason this is an error is because mutexes are not intended to be held " "for long periods of time; they are supposed to only be held to maintain " "short periods of synchronization. This programming contract allows device " "drivers to use mutexes to synchronize with the rest of the kernel during " "interrupts. Interrupts (under FreeBSD) may not sleep. Hence it is " "imperative that no subsystem in the kernel block for an extended period " "while holding a mutex." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:976 msgid "" "To catch such errors, assertions may be added to the kernel that interact " "with the man:witness[4] subsystem to emit a warning or fatal error " "(depending on the system configuration) when a potentially blocking call is " "made while holding a mutex." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:978 msgid "" "In summary, such warnings are non-fatal, however with unfortunate timing " "they could cause undesirable effects ranging from a minor blip in the " "system's responsiveness to a complete system lockup." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:980 msgid "For additional information about locking in FreeBSD see man:locking[9]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:982 #, no-wrap msgid "Why does buildworld/installworld die with the message touch: not found?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:987 msgid "" "This error does not mean that the man:touch[1] utility is missing. The " "error is instead probably due to the dates of the files being set sometime " "in the future. If the CMOS clock is set to local time, run `adjkerntz -i` " "to adjust the kernel clock when booting into single-user mode." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:989 #, no-wrap msgid "User Applications" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:992 #, no-wrap msgid "Where are all the user applications?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:995 msgid "" "Refer to link:https://www.FreeBSD.org/ports/[the ports page] for info on " "software packages ported to FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:999 msgid "" "Most ports should work on all supported versions of FreeBSD. Those that do " "not are specifically marked as such. Each time a FreeBSD release is made, a " "snapshot of the ports tree at the time of release is also included in the [." "filename]#ports/# directory." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1002 msgid "" "FreeBSD supports compressed binary packages to easily install and uninstall " "ports. Use man:pkg[7] to control the installation of packages." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1004 #, no-wrap msgid "How do I download the Ports tree? Should I be using Git?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1007 msgid "" "See extref:{handbook}ports/[Installing the Ports Collection, ports-using-" "installation-methods]" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1009 #, no-wrap msgid "Why can I not build this port on my {rel2-relx} -, or {rel-relx} -STABLE machine?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1014 msgid "" "If the installed FreeBSD version lags significantly behind _-CURRENT_ or _-" "STABLE_, update the Ports Collection using the instructions in extref:" "{handbook}ports/[Using the Ports Collection, ports-using]. If the system is " "up-to-date, someone might have committed a change to the port which works " "for _-CURRENT_ but which broke the port for _-STABLE_. https://bugs.FreeBSD." "org/submit/[Submit] a bug report, since the Ports Collection is supposed to " "work for both the _-CURRENT_ and _-STABLE_ branches." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1016 #, no-wrap msgid "I just tried to build INDEX using make index, and it failed. Why?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1020 msgid "" "First, make sure that the Ports Collection is up-to-date. Errors that " "affect building [.filename]#INDEX# from an up-to-date copy of the Ports " "Collection are high-visibility and are thus almost always fixed immediately." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1023 msgid "" "There are rare cases where [.filename]#INDEX# will not build due to odd " "cases involving `OPTIONS_SET` being set in [.filename]#make.conf#. If you " "suspect that this is the case, try to make [.filename]#INDEX# with those " "variables turned off before reporting it to {freebsd-ports}." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1025 #, no-wrap msgid "I updated the sources, now how do I update my installed ports?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1029 msgid "" "FreeBSD does not include a port upgrading tool, but it does have some tools " "to make the upgrade process somewhat easier. Additional tools are available " "to simplify port handling and are described the extref:{handbook}ports/" "[Upgrading Ports, ports-using] section in the FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1031 #, no-wrap msgid "Do I need to recompile every port each time I perform a major version update?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1035 msgid "" "Yes! While a recent system will run with software compiled under an older " "release, things will randomly crash and fail to work once other ports are " "installed or updated." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1038 msgid "" "When the system is upgraded, various shared libraries, loadable modules, and " "other parts of the system will be replaced with newer versions. " "Applications linked against the older versions may fail to start or, in " "other cases, fail to function properly." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1040 msgid "" "For more information, see extref:{handbook}cutting-edge/[the section on " "upgrades, freebsdupdate-upgrade] in the FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1042 #, no-wrap msgid "Do I need to recompile every port each time I perform a minor version update?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1047 msgid "" "In general, no. FreeBSD developers do their utmost to guarantee binary " "compatibility across all releases with the same major version number. Any " "exceptions will be documented in the Release Notes, and advice given there " "should be followed." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1049 #, no-wrap msgid "Why is /bin/sh so minimal? Why does FreeBSD not use bash or another shell?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1055 msgid "" "Many people need to write shell scripts which will be portable across many " "systems. That is why POSIX(R) specifies the shell and utility commands in " "great detail. Most scripts are written in Bourne shell (man:sh[1]), and " "because several important programming interfaces (man:make[1], man:" "system[3], man:popen[3], and analogues in higher-level scripting languages " "like Perl and Tcl) are specified to use the Bourne shell to interpret " "commands. As the Bourne shell is so often and widely used, it is important " "for it to be quick to start, be deterministic in its behavior, and have a " "small memory footprint." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1060 msgid "" "The existing implementation is our best effort at meeting as many of these " "requirements simultaneously as we can. To keep `/bin/sh` small, we have not " "provided many of the convenience features that other shells have. That is " "why other more featureful shells like `bash`, `scsh`, man:tcsh[1], and `zsh` " "are available. Compare the memory utilization of these shells by looking at " "the \"VSZ\" and \"RSS\" columns in a `ps -u` listing." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:1062 #, no-wrap msgid "Kernel Configuration" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1065 #, no-wrap msgid "I would like to customize my kernel. Is it difficult?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1069 msgid "" "Not at all! Check out the extref:{handbook}kernelconfig/[kernel config " "section of the Handbook]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1074 msgid "" "The new [.filename]#kernel# will be installed to the [.filename]#/boot/" "kernel# directory along with its modules, while the old kernel and its " "modules will be moved to the [.filename]#/boot/kernel.old# directory. If a " "mistake is made in the configuration, simply boot the previous version of " "the kernel." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1077 #, no-wrap msgid "Why is my kernel so big?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1084 msgid "" "`GENERIC` kernels shipped with FreeBSD are compiled in _debug mode_. " "Kernels built in debug mode contain debug data in separate files that are " "used for debugging. FreeBSD releases prior to 11.0 store these debug files " "in the same directory as the kernel itself, [.filename]#/boot/kernel/#. In " "FreeBSD 11.0 and later the debug files are stored in [.filename]#/usr/lib/" "debug/boot/kernel/#. Note that there will be little or no performance loss " "from running a debug kernel, and it is useful to keep one around in case of " "a system panic." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1086 msgid "" "When running low on disk space, there are different options to reduce the " "size of [.filename]#/boot/kernel/# and [.filename]#/usr/lib/debug/#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1088 msgid "" "To not install the symbol files, make sure the following line exists in [." "filename]#/etc/src.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1092 #, no-wrap msgid "WITHOUT_KERNEL_SYMBOLS=yes\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1095 msgid "For more information see man:src.conf[5]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1097 msgid "" "If you want to avoid building debug files altogether, make sure that both of " "the following are true:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1099 msgid "This line does not exist in the kernel configuration file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1103 #, no-wrap msgid "makeoptions DEBUG=-g\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1106 msgid "Do not run man:config[8] with `-g`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1108 msgid "" "Either of the above settings will cause the kernel to be built in debug mode." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1110 msgid "" "To build and install only the specified modules, list them in [.filename]#/" "etc/make.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1114 #, no-wrap msgid "MODULES_OVERRIDE= accf_http ipfw\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1120 msgid "" "Replace _accf_httpd ipfw_ with a list of needed modules. Only the listed " "modules will be built. This reduces the size of the kernel directory and " "decreases the amount of time needed to build the kernel. For more " "information, read [.filename]#/usr/share/examples/etc/make.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1123 msgid "" "Unneeded devices can be removed from the kernel to further reduce the size. " "See <> for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1125 msgid "" "To put any of these options into effect, follow the instructions to extref:" "{handbook}kernelconfig/[build and install, kernelconfig-building] the new " "kernel." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1127 msgid "" "For reference, the FreeBSD 11 amd64 kernel ([.filename]#/boot/kernel/" "kernel#) is approximately 25 MB." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1129 #, no-wrap msgid "Why does every kernel I try to build fail to compile, even GENERIC?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1132 msgid "There are a number of possible causes for this problem:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1135 msgid "" "The source tree is different from the one used to build the currently " "running system. When attempting an upgrade, read [.filename]#/usr/src/" "UPDATING#, paying particular attention to the \"COMMON ITEMS\" section at " "the end." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1137 msgid "" "The `make buildkernel` did not complete successfully. The `make " "buildkernel` target relies on files generated by the `make buildworld` " "target to complete its job correctly." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1141 msgid "" "Even when building <>, it is possible that the source " "tree was fetched at a time when it was either being modified or it was " "broken. Only releases are guaranteed to be buildable, although <> builds fine the majority of the time. Try re-fetching the " "source tree and see if the problem goes away. Try using a different mirror " "in case the previous one is having problems." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1143 #, no-wrap msgid "Which scheduler is in use on a running system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1146 msgid "" "The name of the scheduler currently being used is directly available as the " "value of the `kern.sched.name` sysctl:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1151 #, no-wrap msgid "" "% sysctl kern.sched.name\n" "kern.sched.name: ULE\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1154 #, no-wrap msgid "What is kern.sched.quantum?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1157 msgid "" "`kern.sched.quantum` is the maximum number of ticks a process can run " "without being preempted in the 4BSD scheduler." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:1159 #, no-wrap msgid "Disks, File Systems, and Boot Loaders" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1162 #, no-wrap msgid "How can I add my new hard disk to my FreeBSD system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1165 msgid "" "See the extref:{handbook}disks/[Adding Disks, disks-adding] section in the " "FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1167 #, no-wrap msgid "How do I move my system over to my huge new disk?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1173 msgid "" "The best way is to reinstall the operating system on the new disk, then move " "the user data over. This is highly recommended when tracking _-STABLE_ for " "more than one release or when updating a release instead of installing a new " "one. Install booteasy on both disks with man:boot0cfg[8] and dual boot " "until you are happy with the new configuration. Skip the next paragraph to " "find out how to move the data after doing this." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1176 msgid "" "Alternatively, partition and label the new disk with either man:sade[8] or " "man:gpart[8]. If the disks are MBR-formatted, booteasy can be installed on " "both disks with man:boot0cfg[8] so that the computer can dual boot to the " "old or new system after the copying is done." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1180 msgid "" "Once the new disk set up, the data cannot just be copied. Instead, use " "tools that understand device files and system flags, such as man:dump[8]. " "Although it is recommended to move the data while in single-user mode, it is " "not required." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1184 msgid "" "When the disks are formatted with UFS, never use anything but man:dump[8] " "and man:restore[8] to move the root file system. These commands should also " "be used when moving a single partition to another empty partition. The " "sequence of steps to use `dump` to move the data from one UFS partitions to " "a new partition is:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1188 msgid "`newfs` the new partition." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1189 msgid "`mount` it on a temporary mount point." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1190 msgid "`cd` to that directory." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1191 msgid "`dump` the old partition, piping output to the new one." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1194 msgid "" "For example, to move [.filename]#/dev/ada1s1a# with [.filename]#/mnt# as the " "temporary mount point, type:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1201 #, no-wrap msgid "" "# newfs /dev/ada1s1a\n" "# mount /dev/ada1s1a /mnt\n" "# cd /mnt\n" "# dump 0af - / | restore rf -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1205 msgid "" "Rearranging partitions with `dump` takes a bit more work. To merge a " "partition like [.filename]#/var# into its parent, create the new partition " "large enough for both, move the parent partition as described above, then " "move the child partition into the empty directory that the first move " "created:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1214 #, no-wrap msgid "" "# newfs /dev/ada1s1a\n" "# mount /dev/ada1s1a /mnt\n" "# cd /mnt\n" "# dump 0af - / | restore rf -\n" "# cd var\n" "# dump 0af - /var | restore rf -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1217 msgid "" "To split a directory from its parent, say putting [.filename]#/var# on its " "own partition when it was not before, create both partitions, then mount the " "child partition on the appropriate directory in the temporary mount point, " "then move the old single partition:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1227 #, no-wrap msgid "" "# newfs /dev/ada1s1a\n" "# newfs /dev/ada1s1d\n" "# mount /dev/ada1s1a /mnt\n" "# mkdir /mnt/var\n" "# mount /dev/ada1s1d /mnt/var\n" "# cd /mnt\n" "# dump 0af - / | restore rf -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1231 msgid "" "The man:cpio[1] and man:pax[1] utilities are also available for moving user " "data. These are known to lose file flag information, so use them with " "caution." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1233 #, no-wrap msgid "Which partitions can safely use Soft Updates? I have heard that Soft Updates on / can cause problems. What about Journaled Soft Updates?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1236 msgid "" "Short answer: Soft Updates can usually be safely used on all partitions." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1241 msgid "" "Long answer: Soft Updates has two characteristics that may be undesirable on " "certain partitions. First, a Soft Updates partition has a small chance of " "losing data during a system crash. The partition will not be corrupted as " "the data will simply be lost. Second, Soft Updates can cause temporary " "space shortages." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1249 msgid "" "When using Soft Updates, the kernel can take up to thirty seconds to write " "changes to the physical disk. When a large file is deleted the file still " "resides on disk until the kernel actually performs the deletion. This can " "cause a very simple race condition. Suppose one large file is deleted and " "another large file is immediately created. The first large file is not yet " "actually removed from the physical disk, so the disk might not have enough " "room for the second large file. This will produce an error that the " "partition does not have enough space, even though a large chunk of space has " "just been released. A few seconds later, the file creation works as " "expected." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1252 msgid "" "If a system should crash after the kernel accepts a chunk of data for " "writing to disk, but before that data is actually written out, data could be " "lost. This risk is extremely small, but generally manageable." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1255 msgid "" "These issues affect all partitions using Soft Updates. So, what does this " "mean for the root partition?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1260 msgid "" "Vital information on the root partition changes very rarely. If the system " "crashed during the thirty-second window after such a change is made, it is " "possible that data could be lost. This risk is negligible for most " "applications, but be aware that it exists. If the system cannot tolerate " "this much risk, do not use Soft Updates on the root file system!" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1264 msgid "" "[.filename]#/# is traditionally one of the smallest partitions. If [." "filename]#/tmp# is on [.filename]#/#, there may be intermittent space " "problems. Symlinking [.filename]#/tmp# to [.filename]#/var/tmp# will solve " "this problem." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1266 msgid "" "Finally, man:dump[8] does not work in live mode (-L) on a filesystem, with " "Journaled Soft Updates (SU+J)." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1268 #, no-wrap msgid "Can I mount other foreign file systems under FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1271 msgid "FreeBSD supports a variety of other file systems." msgstr "" #. type: Labeled list #: documentation/content/en/books/faq/_index.adoc:1272 #, no-wrap msgid "UFS" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1275 msgid "" "UFS CD-ROMs can be mounted directly on FreeBSD. Mounting disk partitions " "from Digital UNIX and other systems that support UFS may be more complex, " "depending on the details of the disk partitioning for the operating system " "in question." msgstr "" #. type: Labeled list #: documentation/content/en/books/faq/_index.adoc:1276 #, no-wrap msgid "ext2/ext3" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1279 msgid "" "FreeBSD supports `ext2fs`, `ext3fs`, and `ext4fs` partitions. See man:" "ext2fs[5] for more information." msgstr "" #. type: Labeled list #: documentation/content/en/books/faq/_index.adoc:1280 #, no-wrap msgid "NTFS" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1283 msgid "" "FUSE based NTFS support is available as a port (package:sysutils/fusefs-" "ntfs[]). For more information, see man:ntfs-3g[8]." msgstr "" #. type: Labeled list #: documentation/content/en/books/faq/_index.adoc:1284 #, no-wrap msgid "FAT" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1287 msgid "" "FreeBSD includes a read-write FAT driver. For more information, see man:" "mount_msdosfs[8]." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:1288 #: documentation/content/en/books/faq/_index.adoc:1526 #, no-wrap msgid "ZFS" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1292 msgid "" "FreeBSD includes a port of Sun(TM)'s ZFS driver. The current recommendation " "is to use it only on amd64 platforms with sufficient memory. For more " "information, see man:zfs[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1294 msgid "" "FreeBSD includes the Network File System NFS and the FreeBSD Ports " "Collection provides several FUSE applications to support many other file " "systems." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1296 #, no-wrap msgid "How do I mount a secondary DOS partition?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1301 msgid "" "The secondary DOS partitions are found after _all_ the primary partitions. " "For example, if `E` is the second DOS partition on the second SCSI drive, " "there will be a device file for \"slice 5\" in [.filename]#/dev#. To mount " "it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1305 #, no-wrap msgid "# mount -t msdosfs /dev/da1s5 /dos/e\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1308 #, no-wrap msgid "Is there a cryptographic file system for FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1312 msgid "" "Yes, man:gbde[8] and man:geli[8]. See the extref:{handbook}disks/" "[Encrypting Disk Partitions, disks-encrypting] section of the FreeBSD " "Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1314 #, no-wrap msgid "How do I boot FreeBSD and Linux(R) using GRUB?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1317 msgid "" "To boot FreeBSD using GRUB, add the following to either [.filename]#/boot/" "grub/menu.lst# or [.filename]#/boot/grub/grub.conf#, depending upon which is " "used by the Linux(R) distribution." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1323 #, no-wrap msgid "" "title FreeBSD 9.1\n" "\troot (hd0,a)\n" "\tkernel /boot/loader\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1328 msgid "" "Where _hd0,a_ points to the root partition on the first disk. To specify " "the slice number, use something like this _(hd0,2,a)_. By default, if the " "slice number is omitted, GRUB searches the first slice which has the `a` " "partition." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1330 #, no-wrap msgid "How do I boot FreeBSD and Linux(R) using BootEasy?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1334 msgid "" "Install LILO at the start of the Linux(R) boot partition instead of in the " "Master Boot Record. Then boot LILO from BootEasy." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1336 msgid "" "This is recommended when running Windows(R) and Linux(R) as it makes it " "simpler to get Linux(R) booting again if Windows(R) is reinstalled." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1338 #, no-wrap msgid "How do I change the boot prompt from ??? to something more meaningful?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1342 msgid "" "This cannot be accomplished with the standard boot manager without rewriting " "it. There are a number of other boot managers in the [.filename]#sysutils# " "category of the Ports Collection." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1344 #, no-wrap msgid "How do I use a new removable drive?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1347 msgid "If the drive already has a file system on it, use a command like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1351 #, no-wrap msgid "# mount -t msdosfs /dev/da0s1 /mnt\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1356 msgid "" "If the drive will only be used with FreeBSD systems, partition it with UFS " "or ZFS. This will provide long filename support, improvement in " "performance, and stability. If the drive will be used by other operating " "systems, a more portable choice, such as msdosfs, is better." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1362 #, no-wrap msgid "" "# dd if=/dev/zero of=/dev/da0 count=2\n" "# gpart create -s GPT /dev/da0\n" "# gpart add -t freebsd-ufs /dev/da0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1365 msgid "Finally, create a new file system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1369 #, no-wrap msgid "# newfs /dev/da0p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1372 msgid "and mount it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1376 #, no-wrap msgid "# mount /dev/da0s1 /mnt\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1379 msgid "" "It is a good idea to add a line to [.filename]#/etc/fstab# (see man:" "fstab[5]) so you can just type `mount /mnt` in the future:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1383 #, no-wrap msgid "/dev/da0p1 /mnt ufs rw,noauto 0 0\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1386 #, no-wrap msgid "Why do I get Incorrect super block when mounting a CD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1390 msgid "" "The type of device to mount must be specified. This is described in the " "Handbook section on extref:{handbook}disks/[Using Data CDs, mounting-cd]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1392 #, no-wrap msgid "Why do I get Device not configured when mounting a CD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1396 msgid "" "This generally means that there is no CD in the drive, or the drive is not " "visible on the bus. Refer to the extref:{handbook}disks/[Using Data CDs, " "mounting-cd] section of the Handbook for a detailed discussion of this issue." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1398 #, no-wrap msgid "Why do all non-English characters in filenames show up as ? on my CDs when mounted in FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1402 msgid "" "The CD probably uses the \"Joliet\" extension for storing information about " "files and directories. This is discussed in the Handbook section on extref:" "{handbook}disks/[Using Data CD-ROMs, mounting-cd]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1404 #, no-wrap msgid "A CD burned under FreeBSD cannot be read under any other operating system. Why?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1408 msgid "" "This means a raw file was burned to the CD, rather than creating an ISO 9660 " "file system. Take a look at the Handbook section on extref:{handbook}disks/" "[Using Data CDs]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1410 #, no-wrap msgid "How can I create an image of a data CD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1414 msgid "" "This is discussed in the Handbook section on extref:{handbook}disks/[Writing " "Data to an ISO File System, mkisofs]. For more on working with CD-ROMs, see " "the extref:{handbook}disks/[Creating CDs Section, creating-cds] in the " "Storage chapter in the Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1416 #, no-wrap msgid "Why can I not mount an audio CD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1422 msgid "" "Trying to mount an audio CD will produce an error like `cd9660: /dev/cd0: " "Invalid argument`. This is because `mount` only works on file systems. " "Audio CDs do not have file systems; they just have data. Instead, use a " "program that reads audio CDs, such as the package:audio/xmcd[] package or " "port." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1424 #, no-wrap msgid "How do I mount a multi-session CD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1429 msgid "" "By default, man:mount[8] will attempt to mount the last data track (session) " "of a CD. To load an earlier session, use the `-s` command line argument. " "Refer to man:mount_cd9660[8] for specific examples." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1431 #, no-wrap msgid "How do I let ordinary users mount CD-ROMs, DVDs, USB drives, and other removable media?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1434 msgid "As `root` set the sysctl variable `vfs.usermount` to `1`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1438 #, no-wrap msgid "# sysctl vfs.usermount=1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1441 msgid "" "To make this persist across reboots, add the line `vfs.usermount=1` to [." "filename]#/etc/sysctl.conf# so that it is reset at system boot time." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1444 msgid "" "Users can only mount devices they have read permissions to. To allow users " "to mount a device permissions must be set in [.filename]#/etc/devfs.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1446 msgid "For example, to allow users to mount the first USB drive add:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1452 #, no-wrap msgid "" "# Allow all users to mount a USB drive.\n" "\t own /dev/da0 root:operator\n" "\t perm /dev/da0 0666\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1455 msgid "" "All users can now mount devices they could read onto a directory that they " "own:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1460 #, no-wrap msgid "" "% mkdir ~/my-mount-point\n" "% mount -t msdosfs /dev/da0 ~/my-mount-point\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1463 msgid "Unmounting the device is simple:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1467 #, no-wrap msgid "% umount ~/my-mount-point\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1471 msgid "" "Enabling `vfs.usermount`, however, has negative security implications. A " "better way to access MS-DOS(R) formatted media is to use the package:" "emulators/mtools[] package in the Ports Collection." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1475 msgid "" "The device name used in the previous examples must be changed according to " "the configuration." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1478 #, no-wrap msgid "The du and df commands show different amounts of disk space available. What is going on?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1484 msgid "" "This is due to how these commands actually work. `du` goes through the " "directory tree, measures how large each file is, and presents the totals. " "`df` just asks the file system how much space it has left. They seem to be " "the same thing, but a file without a directory entry will affect `df` but " "not `du`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1493 msgid "" "When a program is using a file, and the file is deleted, the file is not " "really removed from the file system until the program stops using it. The " "file is immediately deleted from the directory listing, however. As an " "example, consider a file large enough to affect the output of `du` and " "`df`. A file being viewed with `more` can be deleted without causing an " "error. The entry is removed from the directory so no other program or user " "can access it. However, `du` shows that it is gone as it has walked the " "directory tree and the file is not listed. `df` shows that it is still " "there, as the file system knows that `more` is still using that space. Once " "the `more` session ends, `du` and `df` will agree." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1500 msgid "" "This situation is common on web servers. Many people set up a FreeBSD web " "server and forget to rotate the log files. The access log fills up [." "filename]#/var#. The new administrator deletes the file, but the system " "still complains that the partition is full. Stopping and restarting the web " "server program would free the file, allowing the system to release the disk " "space. To prevent this from happening, set up man:newsyslog[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1502 msgid "" "Note that Soft Updates can delay the freeing of disk space and it can take " "up to 30 seconds for the change to be visible." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1504 #, no-wrap msgid "How can I add more swap space?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1507 msgid "" "This section extref:{handbook}config/[of the Handbook, adding-swap-space] " "describes how to do this." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1509 #, no-wrap msgid "Why does FreeBSD see my disk as smaller than the manufacturer says it is?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1513 msgid "" "Disk manufacturers calculate gigabytes as a billion bytes each, whereas " "FreeBSD calculates them as 1,073,741,824 bytes each. This explains why, for " "example, FreeBSD's boot messages will report a disk that supposedly has 80 " "GB as holding 76,319 MB." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1515 msgid "" "Also note that FreeBSD will (by default) <> 8% " "of the disk space." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1517 #, no-wrap msgid "How is it possible for a partition to be more than 100% full?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1522 msgid "" "A portion of each UFS partition (8%, by default) is reserved for use by the " "operating system and the `root` user. man:df[1] does not count that space " "when calculating the `Capacity` column, so it can exceed 100%. Notice that " "the `Blocks` column is always greater than the sum of the `Used` and `Avail` " "columns, usually by a factor of 8%." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1524 msgid "For more details, look up `-m` in man:tunefs[8]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1529 #, no-wrap msgid "What is the minimum amount of RAM one should have to run ZFS?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1532 msgid "" "A minimum of 4GB of RAM is required for comfortable usage, but individual " "workloads can vary widely." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1534 #, no-wrap msgid "What is the ZIL and when does it get used?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1542 msgid "" "The ZIL (ZFS intent log) is a write log used to implement posix write " "commitment semantics across crashes. Normally writes are bundled up into " "transaction groups and written to disk when filled (\"Transaction Group " "Commit\"). However syscalls like man:fsync[2] require a commitment that the " "data is written to stable storage before returning. The ZIL is needed for " "writes that have been acknowledged as written but which are not yet on disk " "as part of a transaction. The transaction groups are timestamped. In the " "event of a crash the last valid timestamp is found and missing data is " "merged in from the ZIL." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1544 #, no-wrap msgid "Do I need a SSD for ZIL?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1549 msgid "" "By default, ZFS stores the ZIL in the pool with all the data. If an " "application has a heavy write load, storing the ZIL in a separate device " "that has very fast synchronous, sequential write performance can improve " "overall system performance. For other workloads, a SSD is unlikely to make " "much of an improvement." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1551 #, no-wrap msgid "What is the L2ARC?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1556 msgid "" "The L2ARC is a read cache stored on a fast device such as an SSD. This " "cache is not persistent across reboots. Note that RAM is used as the first " "layer of cache and the L2ARC is only needed if there is insufficient RAM." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1560 msgid "" "L2ARC needs space in the ARC to index it. So, perversely, a working set " "that fits perfectly in the ARC will not fit perfectly any more if a L2ARC is " "used because part of the ARC is holding the L2ARC index, pushing part of the " "working set into the L2ARC which is slower than RAM." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1562 #, no-wrap msgid "Is enabling deduplication advisable?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1565 msgid "Generally speaking, no." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1570 msgid "" "Deduplication takes up a significant amount of RAM and may slow down read " "and write disk access times. Unless one is storing data that is very " "heavily duplicated, such as virtual machine images or user backups, it is " "possible that deduplication will do more harm than good. Another " "consideration is the inability to revert deduplication status. If data is " "written when deduplication is enabled, disabling dedup will not cause those " "blocks which were deduplicated to be replicated until they are next modified." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1573 msgid "" "Deduplication can also lead to some unexpected situations. In particular, " "deleting files may become much slower." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1575 #, no-wrap msgid "I cannot delete or create files on my ZFS pool. How can I fix this?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1580 msgid "" "This could happen because the pool is 100% full. ZFS requires space on the " "disk to write transaction metadata. To restore the pool to a usable state, " "truncate the file to delete:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1584 #, no-wrap msgid "% truncate -s 0 unimportant-file\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1587 msgid "" "File truncation works because a new transaction is not started, new spare " "blocks are created instead." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1591 msgid "" "On systems with additional ZFS dataset tuning, such as deduplication, the " "space may not be immediately available." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1594 #, no-wrap msgid "Is there TRIM support for ZFS on solid state drives?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1598 msgid "" "ZFS in FreeBSD 12.3 and 12.4: TRIM is enabled by default. To disable TRIM: " "add the line below to [.filename]#/etc/sysctl.conf#, then restart the system." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1602 #, no-wrap msgid "vfs.zfs.trim.enabled=0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1605 msgid "" "OpenZFS in FreeBSD 13.0 and greater: see man:zpool-trim[8], and `autotrim` " "in man:zpoolprops[7]." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:1607 #, no-wrap msgid "System Administration" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1610 #, no-wrap msgid "Where are the system start-up configuration files?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1616 msgid "" "The primary configuration file is [.filename]#/etc/defaults/rc.conf# which " "is described in man:rc.conf[5]. System startup scripts such as [.filename]#/" "etc/rc# and [.filename]#/etc/rc.d#, which are described in man:rc[8], " "include this file. _Do not edit this file!_ Instead, to edit an entry in [." "filename]#/etc/defaults/rc.conf#, copy the line into [.filename]#/etc/rc." "conf# and change it there." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1618 msgid "For example, to start man:sshd[8], the included OpenSSH daemon:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1622 #, no-wrap msgid "# echo 'sshd_enable=\"YES\"' >> /etc/rc.conf\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1625 msgid "Alternatively, use man:sysrc[8] to modify [.filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1629 #, no-wrap msgid "# sysrc sshd_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1633 msgid "" "To start up local services, place shell scripts in the [.filename]#/usr/" "local/etc/rc.d# directory. These shell scripts should be set executable, " "the default file mode is `555`." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1635 #, no-wrap msgid "How do I add a user easily?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1638 msgid "" "Use the man:adduser[8] command, or the man:pw[8] command for more " "complicated situations." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1640 msgid "" "To remove the user, use the man:rmuser[8] command or, if necessary, man:" "pw[8]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1642 #, no-wrap msgid "Why do I keep getting messages like root: not found after editing /etc/crontab?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1649 msgid "" "This is normally caused by editing the system crontab. This is not the " "correct way to do things as the system crontab has a different format to the " "per-user crontabs. The system crontab has an extra field, specifying which " "user to run the command as. man:cron[8] assumes this user is the first word " "of the command to execute. Since no such command exists, this error message " "is displayed." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1651 msgid "To delete the extra, incorrect crontab:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1655 #, no-wrap msgid "# crontab -r\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1658 #, no-wrap msgid "Why do I get the error, you are not in the correct group to su root when I try to su to root?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1663 msgid "" "This is a security feature. In order to `su` to `root`, or any other " "account with superuser privileges, the user account must be a member of the " "`wheel` group. If this feature were not there, anybody with an account on a " "system who also found out ``root``'s password would be able to gain " "superuser level access to the system." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1665 msgid "" "To allow someone to `su` to `root`, put them in the `wheel` group using `pw`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1669 #, no-wrap msgid "# pw groupmod wheel -m lisa\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1672 msgid "The above example will add user `lisa` to the group `wheel`." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1674 #, no-wrap msgid "I made a mistake in rc.conf, or another startup file, and now I cannot edit it because the file system is read-only. What should I do?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1680 msgid "" "Restart the system using `boot -s` at the loader prompt to enter single-user " "mode. When prompted for a shell pathname, press kbd:[Enter] and run `mount -" "urw /` to re-mount the root file system in read/write mode. You may also " "need to run `mount -a -t ufs` to mount the file system where your favorite " "editor is defined. If that editor is on a network file system, either " "configure the network manually before mounting the network file systems, or " "use an editor which resides on a local file system, such as man:ed[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1682 msgid "" "In order to use a full screen editor such as man:vi[1] or man:emacs[1], run " "`export TERM=xterm` so that these editors can load the correct data from the " "man:termcap[5] database." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1685 msgid "" "After performing these steps, edit [.filename]#/etc/rc.conf# to fix the " "syntax error. The error message displayed immediately after the kernel boot " "messages should indicate the number of the line in the file which is at " "fault." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1687 #, no-wrap msgid "Why am I having trouble setting up my printer?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1690 msgid "" "See the extref:{handbook}printing/[Handbook entry on printing] for " "troubleshooting tips." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1692 #, no-wrap msgid "How can I correct the keyboard mappings for my system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1695 msgid "" "Refer to the Handbook section on extref:{handbook}l10n/[using localization, " "using-localization], specifically the section on extref:{handbook}l10n/" "[console setup, setting-console]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1697 #, no-wrap msgid "Why can I not get user quotas to work properly?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1701 msgid "" "It is possible that the kernel is not configured to use quotas. In this " "case, add the following line to the kernel configuration file and recompile " "the kernel:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1705 #, no-wrap msgid "options QUOTA\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1708 msgid "" "Refer to the extref:{handbook}disks/[Handbook entry on quotas, quotas] for " "full details." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1709 msgid "Do not turn on quotas on [.filename]#/#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1710 msgid "" "Put the quota file on the file system that the quotas are to be enforced on:" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1715 #, no-wrap msgid "File System" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1717 #, no-wrap msgid "Quota file" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1718 #, no-wrap msgid "[.filename]#/usr#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1720 #, no-wrap msgid "[.filename]#/usr/admin/quotas#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1721 #, no-wrap msgid "[.filename]#/home#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1723 #, no-wrap msgid "[.filename]#/home/admin/quotas#" msgstr "" #. type: Table #: documentation/content/en/books/faq/_index.adoc:1724 #: documentation/content/en/books/faq/_index.adoc:1725 #, no-wrap msgid "..." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1728 #, no-wrap msgid "Does FreeBSD support System V IPC primitives?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1732 msgid "" "Yes, FreeBSD supports System V-style IPC, including shared memory, messages " "and semaphores, in the [.filename]#GENERIC# kernel. With a custom kernel, " "support may be loaded with the [.filename]#sysvshm.ko#, [.filename]#sysvsem." "ko# and [.filename]#sysvmsg.ko# kernel modules, or enabled in the custom " "kernel by adding the following lines to the kernel configuration file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1738 #, no-wrap msgid "" "options SYSVSHM # enable shared memory\n" "options SYSVSEM # enable for semaphores\n" "options SYSVMSG # enable for messaging\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1741 msgid "Recompile and install the kernel." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1743 #, no-wrap msgid "What other mail-server software can I use instead of Sendmail?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1748 msgid "" "The http://www.sendmail.org/[Sendmail] server is the default mail-server " "software for FreeBSD, but it can be replaced with another MTA installed from " "the Ports Collection. Available ports include package:mail/exim[], package:" "mail/postfix[], and package:mail/qmail[]. Search the mailing lists for " "discussions regarding the advantages and disadvantages of the available MTAs." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1750 #, no-wrap msgid "I have forgotten the root password! What do I do?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1757 msgid "" "Do not panic! Restart the system, type `boot -s` at the `Boot:` prompt to " "enter single-user mode. At the question about the shell to use, hit kbd:" "[Enter] which will display a # prompt. Enter `mount -urw /` to remount the " "root file system read/write, then run `mount -a` to remount all the file " "systems. Run `passwd root` to change the `root` password then run man:" "exit[1] to continue booting." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1764 msgid "" "If you are still prompted to give the `root` password when entering the " "single-user mode, it means that the console has been marked as `insecure` in " "[.filename]#/etc/ttys#. In this case, it will be required to boot from a " "FreeBSD installation disk, choose the [.guimenuitem]#Live CD# or [." "guimenuitem]#Shell# at the beginning of the install process and issue the " "commands mentioned above. Mount the specific partition in this case and " "then chroot to it. For example, replace `mount -urw /` with `mount /dev/" "ada0p1 /mnt; chroot /mnt` for a system on _ada0p1_." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:1770 msgid "" "If the root partition cannot be mounted from single-user mode, it is " "possible that the partitions are encrypted and it is impossible to mount " "them without the access keys. For more information see the section about " "encrypted disks in the FreeBSD extref:{handbook}disks/[Handbook, disks-" "encrypting]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1773 #, no-wrap msgid "How do I keep kbd:[Control] + kbd:[Alt] + kbd:[Delete] from rebooting the system?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1776 msgid "" "When using man:vt[4], the default console driver, this can be done by " "setting the following man:sysctl[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1780 #, no-wrap msgid "# sysctl kern.vt.kbd_reboot=0\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1783 #, no-wrap msgid "How do I reformat DOS text files to UNIX(R) ones?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1786 msgid "Use this man:perl[1] command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1790 #, no-wrap msgid "% perl -i.bak -npe 's/\\r\\n/\\n/g' file(s)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1794 msgid "" "where _file(s)_ is one or more files to process. The modification is done " "in-place, with the original file stored with a [.filename]#.bak# extension." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1796 msgid "Alternatively, use man:tr[1]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1800 #, no-wrap msgid "% tr -d '\\r' < dos-text-file > unix-file\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1804 msgid "" "_dos-text-file_ is the file containing DOS text while _unix-file_ will " "contain the converted output. This can be quite a bit faster than using " "`perl`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1807 msgid "" "Yet another way to reformat DOS text files is to use the package:converters/" "dosunix[] port from the Ports Collection. Consult its documentation about " "the details." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1809 #, no-wrap msgid "How do I re-read [.filename]#/etc/rc.conf# and re-start [.filename]#/etc/rc# without a reboot?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1812 msgid "Go into single-user mode and then back to multi-user mode:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1818 #, no-wrap msgid "" "# shutdown now\n" "# return\n" "# exit\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1821 #, no-wrap msgid "I tried to update my system to the latest _-STABLE_, but got _-BETAx_, _-RC_ or __-PRERELEASE__! What is going on?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1828 msgid "" "Short answer: it is just a name. _RC_ stands for \"Release Candidate\". It " "signifies that a release is imminent. In FreeBSD, _-PRERELEASE_ is " "typically synonymous with the code freeze before a release. (For some " "releases, the _-BETA_ label was used in the same way as _-PRERELEASE_.)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1833 msgid "" "Long answer: FreeBSD derives its releases from one of two places. Major, " "dot-zero, releases, such as 9.0-RELEASE are branched from the head of the " "development stream, commonly referred to as <>. Minor " "releases, such as 6.3-RELEASE or 5.2-RELEASE, have been snapshots of the " "active <> branch. Starting with 4.3-RELEASE, each release " "also now has its own branch which can be tracked by people requiring an " "extremely conservative rate of development (typically only security " "advisories)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1842 msgid "" "When a release is about to be made, the branch from which it will be derived " "from has to undergo a certain process. Part of this process is a code " "freeze. When a code freeze is initiated, the name of the branch is changed " "to reflect that it is about to become a release. For example, if the branch " "used to be called 6.2-STABLE, its name will be changed to 6.3-PRERELEASE to " "signify the code freeze and signify that extra pre-release testing should be " "happening. Bug fixes can still be committed to be part of the release. " "When the source code is in shape for the release the name will be changed to " "6.3-RC to signify that a release is about to be made from it. Once in the " "RC stage, only the most critical bugs found can be fixed. Once the release " "(6.3-RELEASE in this example) and release branch have been made, the branch " "will be renamed to 6.3-STABLE." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1844 msgid "" -"For more information on version numbers and the various Subversion branches, " -"refer to the extref:{releng}[Release Engineering] article." +"For more information on version numbers and the various Git branches, refer " +"to the extref:{releng}[Release Engineering] article." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1846 #, no-wrap msgid "I tried to install a new kernel, and the man:chflags[1] failed. How do I get around this?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1850 msgid "" "Short answer: the security level is greater than 0. Reboot directly to " "single-user mode to install the kernel." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1853 msgid "" "Long answer: FreeBSD disallows changing system flags at security levels " "greater than 0. To check the current security level:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1857 #: documentation/content/en/books/faq/_index.adoc:1874 #, no-wrap msgid "# sysctl kern.securelevel\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1861 msgid "" "The security level cannot be lowered in multi-user mode, so boot to single-" "user mode to install the kernel, or change the security level in [." "filename]#/etc/rc.conf# then reboot. See the man:init[8] manual page for " "details on `securelevel`, and see [.filename]#/etc/defaults/rc.conf# and the " "man:rc.conf[5] manual page for more information on [.filename]#rc.conf#." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1863 #, no-wrap msgid "I cannot change the time on my system by more than one second! How do I get around this?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1867 msgid "" "Short answer: the system is at a security level greater than 1. Reboot " "directly to single-user mode to change the date." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1870 msgid "" "Long answer: FreeBSD disallows changing the time by more that one second at " "security levels greater than 1. To check the security level:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1879 msgid "" "The security level cannot be lowered in multi-user mode. Either boot to " "single-user mode to change the date or change the security level in [." "filename]#/etc/rc.conf# and reboot. See the man:init[8] manual page for " "details on `securelevel`, and see [.filename]#/etc/defaults/rc.conf# and the " "man:rc.conf[5] manual page for more information on [.filename]#rc.conf#." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1881 #, no-wrap msgid "Why is rpc.statd using 256 MB of memory?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1886 msgid "" "No, there is no memory leak, and it is not using 256 MB of memory. For " "convenience, `rpc.statd` maps a large amount of memory into its address " "space. There is nothing terribly wrong with this from a technical " "standpoint; it just throws off things like man:top[1] and man:ps[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1888 msgid "" "man:rpc.statd[8] maps its status file ([.filename]#/var/db/statd.status#) " "into its address space; to save worrying about remapping the status file " "later when it needs to grow, it maps the status file with a generous size." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1890 #, no-wrap msgid "Why can I not unset the schg file flag?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1895 msgid "" "The system is running at securelevel greater than 0. Lower the securelevel " "and try again. For more information, see <> and the man:init[8] manual page." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1897 #, no-wrap msgid "What is vnlru?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1901 msgid "" "`vnlru` flushes and frees vnodes when the system hits the `kern.maxvnodes` " "limit. This kernel thread sits mostly idle, and only activates when there " "is a huge amount of RAM and users are accessing tens of thousands of tiny " "files." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1903 #, no-wrap msgid "What do the various memory states displayed by top mean?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1906 msgid "`Active`: pages recently statistically used." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1907 msgid "`Inactive`: pages recently statistically unused." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1908 msgid "" "`Laundry`: pages recently statistically unused but known to be dirty, that " "is, whose contents needs to be paged out before they can be reused." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1909 msgid "`Free`: pages without data content, which can be immediately reused." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1910 msgid "" "`Wired`: pages that are fixed into memory, usually for kernel purposes, but " "also sometimes for special use in processes." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1915 msgid "" "Pages are most often written to disk (sort of a VM sync) when they are in " "the laundry state, but active or inactive pages can also be synced. This " "depends upon the CPU tracking of the modified bit being available, and in " "certain situations there can be an advantage for a block of VM pages to be " "synced, regardless of the queue they belong to. In most common cases, it is " "best to think of the laundry queue as a queue of relatively unused pages " "that might or might not be in the process of being written to disk. The " "inactive queue contains a mix of clean and dirty pages; clean pages near the " "head of the queue are reclaimed immediately to alleviate a free page " "shortage, and dirty pages are moved to the laundry queue for deferred " "processing." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1917 msgid "" "There are some other flags (e.g., busy flag or busy count) that might modify " "some of the described rules." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1919 #, no-wrap msgid "How much free memory is available?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1927 msgid "" "There are a couple of kinds of \"free memory\". The most common is the " "amount of memory immediately available without reclaiming memory already in " "use. That is the size of the free pages queue plus some other reserved " "pages. This amount is exported by the `vm.stats.vm.v_free_count` man:" "sysctl[8], shown, for instance, by man:top[1]. Another kind of \"free " "memory\" is the total amount of virtual memory available to userland " "processes, which depends on the sum of swap space and usable memory. Other " "kinds of \"free memory\" descriptions are also possible, but it is " "relatively useless to define these, but rather it is important to make sure " "that the paging rate is kept low, and to avoid running out of swap space." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1929 #, no-wrap msgid "What is [.filename]#/var/empty#?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1934 msgid "" "[.filename]#/var/empty# is a directory that the man:sshd[8] program uses " "when performing privilege separation. The [.filename]#/var/empty# directory " "is empty, owned by `root` and has the `schg` flag set. This directory " "should not be deleted." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1936 #, no-wrap msgid "I just changed [.filename]#/etc/newsyslog.conf#. How can I check if it does what I expect?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1939 msgid "To see what man:newsyslog[8] will do, use the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1943 #, no-wrap msgid "% newsyslog -nrvv\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1946 #, no-wrap msgid "My time is wrong, how can I change the timezone?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1949 msgid "Use man:tzsetup[8]." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:1951 #, no-wrap msgid "The X Window System and Virtual Consoles" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1954 #, no-wrap msgid "What is the X Window System?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1958 msgid "" "The X Window System (commonly `X11`) is the most widely available windowing " "system capable of running on UNIX(R) or UNIX(R) like systems, including " "FreeBSD. http://www.x.org/wiki/[The X.Org Foundation] administers the " "http://en.wikipedia.org/wiki/X_Window_System_core_protocol[X protocol " "standards], with the current reference implementation, version 11 release " "7.7, so references are often shortened to `X11`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1961 msgid "" "Many implementations are available for different architectures and operating " "systems. An implementation of the server-side code is properly known as an " "`X server`." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1963 #, no-wrap msgid "I want to run Xorg, how do I go about it?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1966 msgid "To install Xorg do one of the following:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1968 msgid "" "Use the package:x11/xorg[] meta-port, which builds and installs every Xorg " "component." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1970 msgid "" "Use package:x11/xorg-minimal[], which builds and installs only the necessary " "Xorg components." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1972 msgid "Install Xorg from FreeBSD packages:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:1976 #, no-wrap msgid "# pkg install xorg\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1979 msgid "" "After the installation of Xorg, follow the instructions from the extref:" "{handbook}x11/[X11 Configuration, x-config] section of the FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1981 #, no-wrap msgid "I tried to run X, but I get a 'No devices detected' error when I type startx. What do I do now?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1986 msgid "" "The system is probably running at a raised `securelevel`. It is not " "possible to start X at a raised `securelevel` because X requires write " "access to man:io[4]. For more information, see at the man:init[8] manual " "page." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1988 msgid "" "There are two solutions to the problem: set the `securelevel` back down to " "zero or run man:xdm[8] (or an alternative display manager) at boot time " "before the `securelevel` is raised." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1990 msgid "" "See <> for more information about running man:xdm[8] at boot time." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:1992 #, no-wrap msgid "Why does my mouse not work with X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:1998 msgid "" "When using man:vt[4], the default console driver, FreeBSD can be configured " "to support a mouse pointer on each virtual screen. To avoid conflicting " "with X, man:vt[4] supports a virtual device called [.filename]#/dev/" "sysmouse#. All mouse events received from the real mouse device are written " "to the man:sysmouse[4] device via man:moused[8]. To use the mouse on one or " "more virtual consoles, _and_ use X, see <> and set up man:moused[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2000 msgid "" "Then edit [.filename]#/etc/X11/xorg.conf# and make sure the following lines " "exist:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2007 #, no-wrap msgid "" "Section \"InputDevice\"\n" " Option \"Protocol\" \"SysMouse\"\n" " Option \"Device\" \"/dev/sysmouse\"\n" ".....\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2011 msgid "" "Starting with Xorg version 7.4, the `InputDevice` sections in [." "filename]#xorg.conf# are ignored in favor of autodetected devices. To " "restore the old behavior, add the following line to the `ServerLayout` or " "`ServerFlags` section:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2015 #, no-wrap msgid "Option \"AutoAddDevices\" \"false\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2019 msgid "" "Some people prefer to use [.filename]#/dev/mouse# under X. To make this " "work, [.filename]#/dev/mouse# should be linked to [.filename]#/dev/sysmouse# " "(see man:sysmouse[4]) by adding the following line to [.filename]#/etc/devfs." "conf# (see man:devfs.conf[5]):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2023 #, no-wrap msgid "link sysmouse mouse\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2026 msgid "" "This link can be created by restarting man:devfs[5] with the following " "command (as `root`):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2030 #, no-wrap msgid "# service devfs restart\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2033 #, no-wrap msgid "My mouse has a fancy wheel. Can I use it in X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2037 msgid "" "Yes, if X is configured for a 5 button mouse. To do this, add the lines " "`Buttons 5` and `ZAxisMapping 4 5` to the \"InputDevice\" section of [." "filename]#/etc/X11/xorg.conf#, as seen in this example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2048 #, no-wrap msgid "" "Section \"InputDevice\"\n" " Identifier \"Mouse1\"\n" " Driver \"mouse\"\n" " Option \"Protocol\" \"auto\"\n" " Option \"Device\" \"/dev/sysmouse\"\n" " Option \"Buttons\" \"5\"\n" " Option \"ZAxisMapping\" \"4 5\"\n" "EndSection\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2051 msgid "" "The mouse can be enabled in Emacs by adding these lines to [.filename]#~/." "emacs#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2057 #, no-wrap msgid "" ";; wheel mouse\n" "(global-set-key [mouse-4] 'scroll-down)\n" "(global-set-key [mouse-5] 'scroll-up)\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2060 #, no-wrap msgid "My laptop has a Synaptics touchpad. Can I use it in X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2063 msgid "Yes, after configuring a few things to make it work." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2065 msgid "" "In order to use the Xorg synaptics driver, first remove `moused_enable` from " "[.filename]#rc.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2067 msgid "" "To enable synaptics, add the following line to [.filename]#/boot/loader." "conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2071 #, no-wrap msgid "hw.psm.synaptics_support=\"1\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2074 msgid "Add the following to [.filename]#/etc/X11/xorg.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2083 #, no-wrap msgid "" "Section \"InputDevice\"\n" "Identifier \"Touchpad0\"\n" "Driver \"synaptics\"\n" "Option \"Protocol\" \"psm\"\n" "Option \"Device\" \"/dev/psm0\"\n" "EndSection\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2086 msgid "Add the following into the \"ServerLayout\" section:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2090 #, no-wrap msgid "InputDevice \"Touchpad0\" \"SendCoreEvents\"\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2093 #, no-wrap msgid "How do I use remote X displays?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2096 msgid "" "For security reasons, the default setting is to not allow a machine to " "remotely open a window." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2098 msgid "" "To enable this feature, start X with the optional `-listen_tcp` argument:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2102 #, no-wrap msgid "% startx -listen_tcp\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2105 #, no-wrap msgid "What is a virtual console and how do I make more?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2108 msgid "" "Virtual consoles provide several simultaneous sessions on the same machine " "without doing anything complicated like setting up a network or running X." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2111 msgid "" "When the system starts, it will display a login prompt on the monitor after " "displaying all the boot messages. Type in your login name and password to " "start working on the first virtual console." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2115 msgid "" "To start another session, perhaps to look at documentation for a program or " "to read mail while waiting for an FTP transfer to finish, hold down kbd:" "[Alt] and press kbd:[F2]. This will display the login prompt for the second " "virtual console. To go back to the original session, press kbd:[Alt+F1]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2118 msgid "" "The default FreeBSD installation has eight virtual consoles enabled. kbd:" "[Alt+F1], kbd:[Alt+F2], kbd:[Alt+F3], and so on will switch between these " "virtual consoles." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2120 msgid "" "To enable more of virtual consoles, edit [.filename]#/etc/ttys# (see man:" "ttys[5]) and add entries for [.filename]#ttyv8# to [.filename]#ttyvc#, after " "the comment on \"Virtual terminals\":" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2129 #, no-wrap msgid "" "# Edit the existing entry for ttyv8 in /etc/ttys and change\n" "# \"off\" to \"on\".\n" "ttyv8 \"/usr/libexec/getty Pc\" xterm on secure\n" "ttyv9 \"/usr/libexec/getty Pc\" xterm on secure\n" "ttyva \"/usr/libexec/getty Pc\" xterm on secure\n" "ttyvb \"/usr/libexec/getty Pc\" xterm on secure\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2134 msgid "" "The more virtual terminals, the more resources that are used. This can be " "problematic on systems with 8 MB RAM or less. Consider changing `secure` to " "`insecure`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2139 msgid "" "In order to run an X server, at least one virtual terminal must be left to " "`off` for it to use. This means that only eleven of the Alt-function keys " "can be used as virtual consoles so that one is left for the X server." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2142 msgid "" "For example, to run X and eleven virtual consoles, the setting for virtual " "terminal 12 should be:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2146 #, no-wrap msgid "ttyvb \"/usr/libexec/getty Pc\" xterm off secure\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2149 msgid "The easiest way to activate the virtual consoles is to reboot." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2151 #, no-wrap msgid "How do I access the virtual consoles from X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2155 msgid "" "Use kbd:[Ctrl+Alt+Fn] to switch back to a virtual console. Press kbd:" "[Ctrl+Alt+F1] to return to the first virtual console." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2157 msgid "Once at a text console, use kbd:[Alt+Fn] to move between them." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2161 msgid "" "To return to the X session, switch to the virtual console running X. If X " "was started from the command line using `startx`, the X session will attach " "to the next unused virtual console, not the text console from which it was " "invoked. For eight active virtual terminals, X will run on the ninth, so " "use kbd:[Alt+F9]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2163 #, no-wrap msgid "How do I start XDM on boot?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2169 msgid "" "There are two schools of thought on how to start man:xdm[8]. One school " "starts `xdm` from [.filename]#/etc/ttys# (see man:ttys[5]) using the " "supplied example, while the other sets `xdm_enable=yes` in [.filename]#/etc/" "rc.conf#. Both are equally valid, and one may work in situations where the " "other does not. In both cases the result is the same: X will pop up a " "graphical login prompt." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2172 msgid "" "The man:ttys[5] method has the advantage of documenting which vty X will " "start on and passing the responsibility of restarting the X server on logout " "to man:init[8]. The man:rc[8] method makes it easy to `kill xdm` if there " "is a problem starting the X server." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2174 msgid "" "When using the man:rc[8] method, `xdm_tty` (default `ttyv8`) can be set in [." "filename]#/etc/rc.conf# to choose which vty man:xdm[8] opens on." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2176 #, no-wrap msgid "Why do I get Couldn't open console when I run xconsole?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2179 msgid "" "When X is started with `startx`, the permissions on [.filename]#/dev/" "console# will _not_ get changed, resulting in things like `xterm -C` and " "`xconsole` not working." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2183 msgid "" "This is because of the way console permissions are set by default. On a " "multi-user system, one does not necessarily want just any user to be able to " "write on the system console. For users who are logging directly onto a " "machine with a VTY, the man:fbtab[5] file exists to solve such problems." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2185 msgid "" "In a nutshell, make sure an uncommented line of the form is in [.filename]#/" "etc/fbtab# (see man:fbtab[5]):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2189 #, no-wrap msgid "/dev/ttyv0 0600 /dev/console\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2192 msgid "" "It will ensure that whomever logs in on [.filename]#/dev/ttyv0# will own the " "console." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2194 #, no-wrap msgid "Why does my PS/2 mouse misbehave under X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2198 msgid "" "The mouse and the mouse driver may have become out of synchronization. In " "rare cases, the driver may also erroneously report synchronization errors:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2202 #, no-wrap msgid "psmintr: out of sync (xxxx != yyyy)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2206 msgid "" "If this happens, disable the synchronization check code by setting the " "driver flags for the PS/2 mouse driver to `0x100`. This can be easiest " "achieved by adding `hint.psm.0.flags=\"0x100\"` to [.filename]#/boot/loader." "conf# and rebooting." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2208 #, no-wrap msgid "How do I reverse the mouse buttons?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2212 msgid "" "Type `xmodmap -e \"pointer = 3 2 1\"`. Add this command to [.filename]#~/." "xinitrc# or [.filename]#~/.xsession# to make it happen automatically." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2214 #, no-wrap msgid "How do I install a splash screen and where do I find them?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2217 msgid "" "The detailed answer for this question can be found in the extref:{handbook}" "[Boot Time Splash Screens, boot-splash] section of the FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2219 #, no-wrap msgid "Can I use the kbd:[Windows] keys on my keyboard in X?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2223 msgid "" "Yes. Use man:xmodmap[1] to define which functions the keys should perform." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2225 msgid "" "Assuming all Windows keyboards are standard, the keycodes for these three " "keys are the following:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2227 msgid "" "115 - kbd:[Windows] key, between the left-hand kbd:[Ctrl] and kbd:[Alt] keys" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2228 msgid "116 - kbd:[Windows] key, to the right of kbd:[AltGr]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2229 msgid "117 - kbd:[Menu], to the left of the right-hand kbd:[Ctrl]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2231 msgid "To have the left kbd:[Windows] key print a comma, try this." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2235 #, no-wrap msgid "# xmodmap -e \"keycode 115 = comma\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2238 msgid "" "To have the kbd:[Windows] key-mappings enabled automatically every time X is " "started, either put the `xmodmap` commands in [.filename]#~/.xinitrc# or, " "preferably, create a [.filename]#~/.xmodmaprc# and include the `xmodmap` " "options, one per line, then add the following line to [.filename]#~/." "xinitrc#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2242 #, no-wrap msgid "xmodmap $HOME/.xmodmaprc\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2246 msgid "" "For example, to map the 3 keys to be kbd:[F13], kbd:[F14], and kbd:[F15], " "respectively. This would make it easy to map them to useful functions " "within applications or the window manager." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2248 msgid "To do this, put the following in [.filename]#~/.xmodmaprc#." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2254 #, no-wrap msgid "" "keycode 115 = F13\n" "keycode 116 = F14\n" "keycode 117 = F15\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2257 msgid "" "For the package:x11-wm/fvwm2[] desktop manager, one could map the keys so " "that kbd:[F13] iconifies or de-iconifies the window the cursor is in, kbd:" "[F14] brings the window the cursor is in to the front or, if it is already " "at the front, pushes it to the back, and kbd:[F15] pops up the main " "Workplace menu even if the cursor is not on the desktop, which is useful " "when no part of the desktop is visible." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2259 msgid "" "The following entries in [.filename]#~/.fvwmrc# implement the aforementioned " "setup:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2265 #, no-wrap msgid "" "Key F13 FTIWS A Iconify\n" "Key F14 FTIWS A RaiseLower\n" "Key F15 A A Menu Workplace Nop\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2268 #, no-wrap msgid "How can I get 3D hardware acceleration for OpenGL(R)?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2272 msgid "" "The availability of 3D acceleration depends on the version of Xorg and the " "type of video chip. For an nVidia chip, use the binary drivers provided for " "FreeBSD by installing one of the following ports:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2274 msgid "" "The latest versions of nVidia cards are supported by the package:x11/nvidia-" "driver[] port." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2276 msgid "Older drivers are available as:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2278 msgid "package:x11/nvidia-driver-390[]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2279 msgid "package:x11/nvidia-driver-340[]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2280 msgid "package:x11/nvidia-driver-304[]" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2282 msgid "" "nVidia provides detailed information on which card is supported by which " "driver on their web site: http://www.nvidia.com/object/IO_32667.html[http://" "www.nvidia.com/object/IO_32667.html]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2284 msgid "" "For Matrox G200/G400, check the package:x11-drivers/xf86-video-mga[] port." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2286 msgid "" "For ATI Rage 128 and Radeon see man:ati[4], man:r128[4] and man:radeon[4]." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2288 #, no-wrap msgid "Networking" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2291 #, no-wrap msgid "Where can I get information on diskless booting?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2295 msgid "" "\"Diskless booting\" means that the FreeBSD box is booted over a network, " "and reads the necessary files from a server instead of its hard disk. For " "full details, see extref:{handbook}advanced-networking/[the Handbook entry " "on diskless booting, network-diskless]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2297 #, no-wrap msgid "Can a FreeBSD box be used as a dedicated network router?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2302 msgid "" "Yes. Refer to the Handbook entry on extref:{handbook}advanced-networking/" "[advanced networking, advanced-networking], specifically the section on " "extref:{handbook}advanced-networking/[routing and gateways, network-routing]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2304 #, no-wrap msgid "Does FreeBSD support NAT or Masquerading?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2309 msgid "" "Yes. For instructions on how to use NAT over a PPP connection, see the " "extref:{handbook}ppp-and-slip/[Handbook entry on PPP, userppp]. To use NAT " "over some other sort of network connection, look at the extref:{handbook}" "[natd, network-natd] section of the Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2311 #, no-wrap msgid "How can I set up Ethernet aliases?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2314 msgid "" "If the alias is on the same subnet as an address already configured on the " "interface, add `netmask 0xffffffff` to this command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2318 #, no-wrap msgid "# ifconfig ed0 alias 192.0.2.2 netmask 0xffffffff\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2321 msgid "Otherwise, specify the network address and netmask as usual:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2325 #, no-wrap msgid "# ifconfig ed0 alias 172.16.141.5 netmask 0xffffff00\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2328 msgid "" "More information can be found in the FreeBSD extref:{handbook}config/" "[Handbook, configtuning-virtual-hosts]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2330 #, no-wrap msgid "Why can I not NFS-mount from a Linux(R) box?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2333 msgid "" "Some versions of the Linux(R) NFS code only accept mount requests from a " "privileged port; try to issue the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2337 #, no-wrap msgid "# mount -o -P linuxbox:/blah /mnt\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2340 #, no-wrap msgid "Why does mountd keep telling me it can't change attributes and that I have a bad exports list on my FreeBSD NFS server?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2344 msgid "" "The most frequent problem is not understanding the correct format of [." "filename]#/etc/exports#. Review man:exports[5] and the extref:{handbook}" "network-servers/[NFS, network-nfs] entry in the Handbook, especially the " "section on extref:{handbook}[configuring NFS, configuring-nfs]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2346 #, no-wrap msgid "How do I enable IP multicast support?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2349 msgid "" "Install the package:net/mrouted[] package or port and add " "`mrouted_enable=\"YES\"` to [.filename]#/etc/rc.conf# start this service at " "boot time." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2351 #, no-wrap msgid "Why do I have to use the FQDN for hosts on my site?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2354 msgid "" "See the answer in the FreeBSD extref:{handbook}mail/[Handbook, mail-trouble]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2356 #, no-wrap msgid "Why do I get an error, Permission denied, for all networking operations?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2359 msgid "" "If the kernel is compiled with the `IPFIREWALL` option, be aware that the " "default policy is to deny all packets that are not explicitly allowed." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2361 msgid "" "If the firewall is unintentionally misconfigured, restore network " "operability by typing the following as `root`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2365 #, no-wrap msgid "# ipfw add 65534 allow all from any to any\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2368 msgid "Consider setting `firewall_type=\"open\"` in [.filename]#/etc/rc.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2370 msgid "" "For further information on configuring this firewall, see the extref:" "{handbook}firewalls/[Handbook chapter, firewalls-ipfw]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2372 #, no-wrap msgid "Why is my `ipfw` “fwd” rule to redirect a service to another machine not working?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2377 msgid "" "Possibly because network address translation (NAT) is needed instead of just " "forwarding packets. A \"fwd\" rule only forwards packets, it does not " "actually change the data inside the packet. Consider this rule:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2381 #, no-wrap msgid "01000 fwd 10.0.0.1 from any to foo 21\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2388 msgid "" "When a packet with a destination address of _foo_ arrives at the machine " "with this rule, the packet is forwarded to _10.0.0.1_, but it still has the " "destination address of _foo_. The destination address of the packet is not " "changed to _10.0.0.1_. Most machines would probably drop a packet that they " "receive with a destination address that is not their own. Therefore, using " "a \"fwd\" rule does not often work the way the user expects. This behavior " "is a feature and not a bug." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2390 msgid "" "See the <>, the man:natd[8] " "manual, or one of the several port redirecting utilities in the link:https://" "www.FreeBSD.org/ports/[Ports Collection] for a correct way to do this." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2392 #, no-wrap msgid "How can I redirect service requests from one machine to another?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2396 msgid "" "FTP and other service requests can be redirected with the package:sysutils/" "socket[] package or port. Replace the entry for the service in [.filename]#/" "etc/inetd.conf# to call `socket`, as seen in this example for ftpd:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2400 #, no-wrap msgid "ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.example.com ftp\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2403 msgid "" "where _ftp.example.com_ and _ftp_ are the host and port to redirect to, " "respectively." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2405 #, no-wrap msgid "Where can I get a bandwidth management tool?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2411 msgid "" "There are three bandwidth management tools available for FreeBSD. man:" "dummynet[4] is integrated into FreeBSD as part of man:ipfw[4]. http://www." "sonycsl.co.jp/person/kjc/programs.html[ALTQ] has been integrated into " "FreeBSD as part of man:pf[4]. Bandwidth Manager from http://www.etinc.com/" "[Emerging Technologies] is a commercial product." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2413 #, no-wrap msgid "Why do I get /dev/bpf0: device not configured?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2417 msgid "" "The running application requires the Berkeley Packet Filter (man:bpf[4]), " "but it was removed from a custom kernel. Add this to the kernel config file " "and build a new kernel:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2421 #, no-wrap msgid "device bpf # Berkeley Packet Filter\n" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2424 #, no-wrap msgid "How do I mount a disk from a Windows(R) machine that is on my network, like smbmount in Linux(R)?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2429 msgid "" "Use the SMBFS toolset. It includes a set of kernel modifications and a set " "of userland programs. The programs and information are available as man:" "mount_smbfs[8] in the base system." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2431 #, no-wrap msgid "What are these messages about: Limiting icmp/open port/closed port response in my log files?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2437 msgid "" "This kernel message indicates that some activity is provoking it to send a " "large amount of ICMP or TCP reset (RST) responses. ICMP responses are often " "generated as a result of attempted connections to unused UDP ports. TCP " "resets are generated as a result of attempted connections to unopened TCP " "ports. Among others, these are the kinds of activities which may cause " "these messages:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2439 msgid "" "Brute-force denial of service (DoS) attacks (as opposed to single-packet " "attacks which exploit a specific vulnerability)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2440 msgid "" "Port scans which attempt to connect to a large number of ports (as opposed " "to only trying a few well-known ports)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2444 msgid "" "The first number in the message indicates how many packets the kernel would " "have sent if the limit was not in place, and the second indicates the " "limit. This limit is controlled using `net.inet.icmp.icmplim`. This " "example sets the limit to `300` packets per second:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2448 #, no-wrap msgid "# sysctl net.inet.icmp.icmplim=300\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2451 msgid "" "To disable these messages without disabling response limiting, use `net.inet." "icmp.icmplim_output` to disable the output:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2455 #, no-wrap msgid "# sysctl net.inet.icmp.icmplim_output=0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2459 msgid "" "Finally, to disable response limiting completely, set `net.inet.icmp." "icmplim` to `0`. Disabling response limiting is discouraged for the reasons " "listed above." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2461 #, no-wrap msgid "What are these arp: unknown hardware address format error messages?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2467 msgid "" "This means that some device on the local Ethernet is using a MAC address in " "a format that FreeBSD does not recognize. This is probably caused by " "someone experimenting with an Ethernet card somewhere else on the network. " "This is most commonly seen on cable modem networks. It is harmless, and " "should not affect the performance of the FreeBSD system." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2469 #, no-wrap msgid "Why do I keep seeing messages like: 192.168.0.10 is on fxp1 but got reply from 00:15:17:67:cf:82 on rl0, and how do I disable it?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2473 msgid "" "A packet is coming from outside the network unexpectedly. To disable them, " "set `net.link.ether.inet.log_arp_wrong_iface` to `0`." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2475 #, no-wrap msgid "How do I compile an IPv6 only kernel?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2478 msgid "Configure your kernel with these settings:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2486 #, no-wrap msgid "" "include GENERIC\n" "ident GENERIC-IPV6ONLY\n" "makeoptions MKMODULESENV+=\"WITHOUT_INET_SUPPORT=\"\n" "nooptions INET\n" "nodevice gre\n" msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2489 #, no-wrap msgid "Security" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2492 #, no-wrap msgid "What is a sandbox?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2496 msgid "\"Sandbox\" is a security term. It can mean two things:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2498 msgid "" "A process which is placed inside a set of virtual walls that are designed to " "prevent someone who breaks into the process from being able to break into " "the wider system." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2501 msgid "" "The process is only able to run inside the walls. Since nothing the process " "does in regards to executing code is supposed to be able to breach the " "walls, a detailed audit of its code is not needed in order to be able to say " "certain things about its security." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2504 msgid "" "The walls might be a user ID, for example. This is the definition used in " "the man:security[7] and man:named[8] man pages." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2509 msgid "" "Take the `ntalk` service, for example (see man:inetd[8]). This service used " "to run as user ID `root`. Now it runs as user ID `tty`. The `tty` user is " "a sandbox designed to make it more difficult for someone who has " "successfully hacked into the system via `ntalk` from being able to hack " "beyond that user ID." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2511 msgid "" "A process which is placed inside a simulation of the machine. It means that " "someone who is able to break into the process may believe that he can break " "into the wider machine but is, in fact, only breaking into a simulation of " "that machine and not modifying any real data." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2513 msgid "" "The most common way to accomplish this is to build a simulated environment " "in a subdirectory and then run the processes in that directory chrooted so " "that [.filename]#/# for that process is this directory, not the real [." "filename]#/# of the system)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2516 msgid "" "Another common use is to mount an underlying file system read-only and then " "create a file system layer on top of it that gives a process a seemingly " "writeable view into that file system. The process may believe it is able to " "write to those files, but only the process sees the effects - other " "processes in the system do not, necessarily." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2518 msgid "" "An attempt is made to make this sort of sandbox so transparent that the user " "(or hacker) does not realize that he is sitting in it." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2521 msgid "" "UNIX(R) implements two core sandboxes. One is at the process level, and one " "is at the userid level." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2524 msgid "" "Every UNIX(R) process is completely firewalled off from every other UNIX(R) " "process. One process cannot modify the address space of another." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2528 msgid "" "A UNIX(R) process is owned by a particular userid. If the user ID is not " "the `root` user, it serves to firewall the process off from processes owned " "by other users. The user ID is also used to firewall off on-disk data." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2530 #, no-wrap msgid "What is securelevel?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2536 msgid "" "`securelevel` is a security mechanism implemented in the kernel. When the " "securelevel is positive, the kernel restricts certain tasks; not even the " "superuser (`root`) is allowed to do them. The securelevel mechanism limits " "the ability to:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2538 msgid "Unset certain file flags, such as `schg` (the system immutable flag)." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2539 msgid "" "Write to kernel memory via [.filename]#/dev/mem# and [.filename]#/dev/kmem#." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2540 msgid "Load kernel modules." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2541 msgid "Alter firewall rules." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2543 msgid "To check the status of the securelevel on a running system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2547 #, no-wrap msgid "# sysctl -n kern.securelevel\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2551 msgid "" "The output contains the current value of the securelevel. If it is greater " "than 0, at least some of the securelevel's protections are enabled." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2554 msgid "" "The securelevel of a running system cannot be lowered as this would defeat " "its purpose. If a task requires that the securelevel be non-positive, " "change the `kern_securelevel` and `kern_securelevel_enable` variables in [." "filename]#/etc/rc.conf# and reboot." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2556 msgid "" "For more information on securelevel and the specific things all the levels " "do, consult man:init[8]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2561 msgid "" "Securelevel is not a silver bullet; it has many known deficiencies. More " "often than not, it provides a false sense of security." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2565 msgid "" "One of its biggest problems is that in order for it to be at all effective, " "all files used in the boot process up until the securelevel is set must be " "protected. If an attacker can get the system to execute their code prior to " "the securelevel being set (which happens quite late in the boot process " "since some things the system must do at start-up cannot be done at an " "elevated securelevel), its protections are invalidated. While this task of " "protecting all files used in the boot process is not technically impossible, " "if it is achieved, system maintenance will become a nightmare since one " "would have to take the system down, at least to single-user mode, to modify " "a configuration file." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2569 msgid "" "This point and others are often discussed on the mailing lists, particularly " "the {freebsd-security}. Search the archives link:https://www.FreeBSD.org/" "search/[here] for an extensive discussion. A more fine-grained mechanism is " "preferred." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2572 #, no-wrap msgid "What is this UID 0 toor account? Have I been compromised?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2579 msgid "" "Do not worry. `toor` is an \"alternative\" superuser account, where toor is " "root spelled backwards. It is intended to be used with a non-standard shell " "so the default shell for `root` does not need to change. This is important " "as shells which are not part of the base distribution, but are instead " "installed from ports or packages, are installed in [.filename]#/usr/local/" "bin# which, by default, resides on a different file system. If ``root``'s " "shell is located in [.filename]#/usr/local/bin# and the file system " "containing [.filename]#/usr/local/bin#) is not mounted, `root` will not be " "able to log in to fix a problem and will have to reboot into single-user " "mode in order to enter the path to a shell." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2582 msgid "" "Some people use `toor` for day-to-day `root` tasks with a non-standard " "shell, leaving `root`, with a standard shell, for single-user mode or " "emergencies. By default, a user cannot log in using `toor` as it does not " "have a password, so log in as `root` and set a password for `toor` before " "using it to login." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2584 #, no-wrap msgid "Serial Communications" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2587 msgid "" "This section answers common questions about serial communications with " "FreeBSD." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2589 #, no-wrap msgid "How do I get the boot: prompt to show on the serial console?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2592 msgid "" "See extref:{handbook}serialcomms/[this section of the Handbook, " "serialconsole-setup]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2594 #, no-wrap msgid "How do I tell if FreeBSD found my serial ports or modem cards?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2598 msgid "" "As the FreeBSD kernel boots, it will probe for the serial ports for which " "the kernel is configured. Either watch the boot messages closely or run " "this command after the system is up and running:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2605 #, no-wrap msgid "" "% grep -E '^(sio|uart)[0-9]' < /var/run/dmesg.boot\n" "uart0: <16550 or compatible> port 0x3f8-0x3ff irq 4 flags 0x10 on acpi0\n" "uart0: console (115200,n,8,1)\n" "uart1: <16550 or compatible> port 0x2f8-2x3ff irq 3 on acpi0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2611 msgid "" "This example shows two serial ports. The first is on IRQ4, port address " "`0x3f8`, and has a 16550-type UART chip. The second uses the same kind of " "chip but is on IRQ3 and is at port address `0x2f8`. Internal modem cards " "are treated just like serial ports, except that they always have a modem " "attached to the port." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2614 msgid "" "The [.filename]#GENERIC# kernel includes support for two serial ports using " "the same IRQ and port address settings in the above example. If these " "settings are not right for the system, or if there are more modem cards or " "serial ports than the kernel is configured for, reconfigure using the " "instructions in <> for more details." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2616 #, no-wrap msgid "How do I access the serial ports on FreeBSD? (x86-specific)" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2620 msgid "" "The third serial port, [.filename]#sio2#, or [.filename]#COM3#, is on [." "filename]#/dev/cuad2# for dial-out devices, and on [.filename]#/dev/ttyd2# " "for dial-in devices. What is the difference between these two classes of " "devices?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2626 msgid "" "When opening [.filename]#/dev/ttydX# in blocking mode, a process will wait " "for the corresponding [.filename]#cuadX# device to become inactive, and then " "wait for the carrier detect line to go active. When the [.filename]#cuadX# " "device is opened, it makes sure the serial port is not already in use by the " "[.filename]#ttydX# device. If the port is available, it steals it from the " "[.filename]#ttydX# device. Also, the [.filename]#cuadX# device does not " "care about carrier detect. With this scheme and an auto-answer modem, " "remote users can log in and local users can still dial out with the same " "modem and the system will take care of all the conflicts." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2628 #, no-wrap msgid "How do I enable support for a multi-port serial card?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2636 msgid "" "The section on kernel configuration provides information about configuring " "the kernel. For a multi-port serial card, place an man:sio[4] line for each " "serial port on the card in the man:device.hints[5] file. But place the IRQ " "specifiers on only one of the entries. All of the ports on the card should " "share one IRQ. For consistency, use the last serial port to specify the " "IRQ. Also, specify the following option in the kernel configuration file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2640 #, no-wrap msgid "options COM_MULTIPORT\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2643 msgid "" "The following [.filename]#/boot/device.hints# example is for an AST 4-port " "serial card on IRQ 12:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2659 #, no-wrap msgid "" "hint.sio.4.at=\"isa\"\n" "hint.sio.4.port=\"0x2a0\"\n" "hint.sio.4.flags=\"0x701\"\n" "hint.sio.5.at=\"isa\"\n" "hint.sio.5.port=\"0x2a8\"\n" "hint.sio.5.flags=\"0x701\"\n" "hint.sio.6.at=\"isa\"\n" "hint.sio.6.port=\"0x2b0\"\n" "hint.sio.6.flags=\"0x701\"\n" "hint.sio.7.at=\"isa\"\n" "hint.sio.7.port=\"0x2b8\"\n" "hint.sio.7.flags=\"0x701\"\n" "hint.sio.7.irq=\"12\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2662 msgid "" "The flags indicate that the master port has minor number `7` (`0x700`), and " "all the ports share an IRQ (`0x001`)." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2664 #, no-wrap msgid "Can I set the default serial parameters for a port?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2667 msgid "" "See the extref:{handbook}serialcomms/[Serial Communications, serial-hw-" "config] section in the FreeBSD Handbook." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2669 #, no-wrap msgid "Why can I not run tip or cu?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2673 msgid "" "The built-in man:tip[1] and man:cu[1] utilities can only access the [." "filename]#/var/spool/lock# directory via user `uucp` and group `dialer`. " "Use the `dialer` group to control who has access to the modem or remote " "systems by adding user accounts to `dialer`." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2675 msgid "" "Alternatively, everyone can be configured to run man:tip[1] and man:cu[1] by " "typing:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2680 #, no-wrap msgid "" "# chmod 4511 /usr/bin/cu\n" "# chmod 4511 /usr/bin/tip\n" msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2683 #, no-wrap msgid "Miscellaneous Questions" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2686 #, no-wrap msgid "FreeBSD uses a lot of swap space even when the computer has free memory left. Why?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2690 msgid "" "FreeBSD will proactively move entirely idle, unused pages of main memory " "into swap in order to make more main memory available for active use. This " "heavy use of swap is balanced by using the extra free memory for caching." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2693 msgid "" "Note that while FreeBSD is proactive in this regard, it does not arbitrarily " "decide to swap pages when the system is truly idle. Thus, the system will " "not be all paged out after leaving it idle overnight." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2695 #, no-wrap msgid "Why does top show very little free memory even when I have very few programs running?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2702 msgid "" "The simple answer is that free memory is wasted memory. Any memory that " "programs do not actively allocate is used within the FreeBSD kernel as disk " "cache. The values shown by man:top[1] labeled as `Inact` and `Laundry` are " "cached data at different aging levels. This cached data means the system " "does not have to access a slow disk again for data it has accessed recently, " "thus increasing overall performance. In general, a low value shown for " "`Free` memory in man:top[1] is good, provided it is not _very_ low." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2704 #, no-wrap msgid "Why will `chmod` not change the permissions on symlinks?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2708 msgid "" "Symlinks do not have permissions, and by default, man:chmod[1] will follow " "symlinks to change the permissions on the source file, if possible. For the " "file, [.filename]#foo# with a symlink named [.filename]#bar#, this command " "will always succeed." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2712 #, no-wrap msgid "% chmod g-w bar\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2715 msgid "However, the permissions on [.filename]#bar# will not have changed." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2718 msgid "" "When changing modes of the file hierarchies rooted in the files instead of " "the files themselves, use either `-H` or `-L` together with `-R` to make " "this work. See man:chmod[1] and man:symlink[7] for more information." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2725 msgid "" "`-R` does a _recursive_ man:chmod[1]. Be careful about specifying " "directories or symlinks to directories to man:chmod[1]. To change the " "permissions of a directory referenced by a symlink, use man:chmod[1] without " "any options and follow the symlink with a trailing slash ([.filename]#/#). " "For example, if [.filename]#foo# is a symlink to directory [.filename]#bar#, " "to change the permissions of [.filename]#foo# (actually [.filename]#bar#), " "do something like:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/faq/_index.adoc:2729 #, no-wrap msgid "% chmod 555 foo/\n" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2732 msgid "" "With the trailing slash, man:chmod[1] will follow the symlink, [." "filename]#foo#, to change the permissions of the directory, [.filename]#bar#." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2735 #, no-wrap msgid "Can I run DOS binaries under FreeBSD?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2739 msgid "" "Yes. A DOS emulation program, package:emulators/doscmd[], is available in " "the FreeBSD Ports Collection." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2742 msgid "" "If doscmd will not suffice, package:emulators/pcemu[] emulates an 8088 and " "enough BIOS services to run many DOS text-mode applications. It requires " "the X Window System." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2745 msgid "" "The Ports Collection also has package:emulators/dosbox[]. The main focus of " "this application is emulating old DOS games using the local file system for " "files." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2747 #, no-wrap msgid "What do I need to do to translate a FreeBSD document into my native language?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2750 msgid "" "See the extref:{fdp-primer}[Translation FAQ, translations] in the FreeBSD " "Documentation Project Primer." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2752 #, no-wrap msgid "Why does my email to any address at FreeBSD.org bounce?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2756 msgid "" "The `FreeBSD.org` mail system implements some Postfix checks on incoming " "mail and rejects mail that is either from misconfigured relays or otherwise " "appears likely to be spam. Some of the specific requirements are:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2758 msgid "" "The IP address of the SMTP client must \"reverse-resolve\" to a forward " "confirmed hostname." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2759 msgid "" "The fully-qualified hostname given in the SMTP conversation (either HELO or " "EHLO) must resolve to the IP address of the client." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2761 msgid "Other advice to help mail reach its destination include:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2763 msgid "" "Mail should be sent in plain text, and messages sent to mailing lists should " "generally be no more than 200KB in length." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2765 msgid "" "Avoid excessive cross posting. Choose _one_ mailing list which seems most " "relevant and send it there." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2769 msgid "" "If you still have trouble with email infrastructure at `FreeBSD.org`, send a " "note with the details to mailto:postmaster@freebsd.org[postmaster@freebsd." "org]; Include a date/time interval so that logs may be reviewed - and note " "that we only keep one week's worth of mail logs. (Be sure to specify the " "time zone or offset from UTC.)" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2771 #, no-wrap msgid "Where can I find a free FreeBSD account?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2775 msgid "" "While FreeBSD does not provide open access to any of their servers, others " "do provide open access UNIX(R) systems. The charge varies and limited " "services may be available." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2782 msgid "" "http://www.arbornet.org/[Arbornet, Inc], also known as _M-Net_, has been " "providing open access to UNIX(R) systems since 1983. Starting on an Altos " "running System III, the site switched to BSD/OS in 1991. In June of 2000, " "the site switched again to FreeBSD. _M-Net_ can be accessed via telnet and " "SSH and provides basic access to the entire FreeBSD software suite. " "However, network access is limited to members and patrons who donate to the " "system, which is run as a non-profit organization. _M-Net_ also provides an " "bulletin board system and interactive chat." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2784 #, no-wrap msgid "What is the cute little red guy's name?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2789 msgid "" "He does not have one, and is just called \"the BSD daemon\". If you insist " "upon using a name, call him \"beastie\". Note that \"beastie\" is " "pronounced \"BSD\"." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2791 msgid "" "More about the BSD daemon is available on his http://www.mckusick.com/" "beastie/index.html[home page]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2793 #, no-wrap msgid "Can I use the BSD daemon image?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2798 msgid "" "Perhaps. The BSD daemon is copyrighted by Marshall Kirk McKusick. Check " "his http://www.mckusick.com/beastie/mainpage/copyright.html[Statement on the " "Use of the BSD Daemon Figure] for detailed usage terms." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2802 msgid "" "In summary, the image can be used in a tasteful manner, for personal use, so " "long as appropriate credit is given. Before using the logo commercially, " "contact {mckusick} for permission. More details are available on the http://" "www.mckusick.com/beastie/index.html[BSD Daemon's home page]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2804 #, no-wrap msgid "Do you have any BSD daemon images I could use?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2807 msgid "" "Xfig and eps drawings are available under [.filename]#/usr/share/examples/" "BSD_daemon/#." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2809 #, no-wrap msgid "I have seen an acronym or other term on the mailing lists and I do not understand what it means. Where should I look?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2812 msgid "Refer to the extref:{handbook}glossary/[FreeBSD Glossary]." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2814 #, no-wrap msgid "Why should I care what color the bikeshed is?" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2820 msgid "" "The really, really short answer is that you should not. The somewhat longer " "answer is that just because you are capable of building a bikeshed does not " "mean you should stop others from building one just because you do not like " "the color they plan to paint it. This is a metaphor indicating that you " "need not argue about every little feature just because you know enough to do " "so. Some people have commented that the amount of noise generated by a " "change is inversely proportional to the complexity of the change." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/faq/_index.adoc:2823 msgid "" "The longer and more complete answer is that after a very long argument about " "whether man:sleep[1] should take fractional second arguments, {phk} posted a " "long message entitled link:http://www.bikeshed.com[A bike shed (any color " "will do) on greener grass...]. The appropriate portions of that message are " "quoted below." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2826 msgid "“What is it about this bike shed?” some of you have asked me." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2830 msgid "" "It is a long story, or rather it is an old story, but it is quite short " "actually. C. Northcote Parkinson wrote a book in the early 1960s, called " "“Parkinson's Law”, which contains a lot of insight into the dynamics of " "management." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2834 msgid "" "In the specific example involving the bike shed, the other vital component " "is an atomic power-plant, I guess that illustrates the age of the book." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2836 msgid "" "Parkinson shows how you can go into the board of directors and get approval " "for building a multi-million or even billion dollar atomic power plant, but " "if you want to build a bike shed you will be tangled up in endless " "discussions." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2839 msgid "" "Parkinson explains that this is because an atomic plant is so vast, so " "expensive and so complicated that people cannot grasp it, and rather than " "try, they fall back on the assumption that somebody else checked all the " "details before it got this far. Richard P. Feynmann gives a couple of " "interesting, and very much to the point, examples relating to Los Alamos in " "his books." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2844 msgid "" "A bike shed on the other hand. Anyone can build one of those over a " "weekend, and still have time to watch the game on TV. So no matter how well " "prepared, no matter how reasonable you are with your proposal, somebody will " "seize the chance to show that he is doing his job, that he is paying " "attention, that he is here." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2850 msgid "" "In Denmark we call it “setting your fingerprint”. It is about personal " "pride and prestige, it is about being able to point somewhere and say " "“There! I did that.”. It is a strong trait in politicians, but present in " "most people given the chance. Just think about footsteps in wet cement." msgstr "" #. type: delimited block * 4 #: documentation/content/en/books/faq/_index.adoc:2852 msgid "" "--Poul-Henning Kamp on freebsd-hackers, October 2, 1999" msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2855 #, no-wrap msgid "The FreeBSD Funnies" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2858 #, no-wrap msgid "How cool is FreeBSD?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2863 msgid "" "_Q._ Has anyone done any temperature testing while running FreeBSD? I know " "Linux(R) runs cooler than DOS, but have never seen a mention of FreeBSD. It " "seems to run really hot." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2870 msgid "" "_A._ No, but we have done numerous taste tests on blindfolded volunteers who " "have also had 250 micrograms of LSD-25 administered beforehand. 35% of the " "volunteers said that FreeBSD tasted sort of orange, whereas Linux(R) tasted " "like purple haze. Neither group mentioned any significant variances in " "temperature. We eventually had to throw the results of this survey out " "entirely anyway when we found that too many volunteers were wandering out of " "the room during the tests, thus skewing the results. We think most of the " "volunteers are at Apple now, working on their new \"scratch and sniff\" " "GUI. It is a funny old business we are in!" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2873 msgid "" "Seriously, FreeBSD uses the HLT (halt) instruction when the system is idle " "thus lowering its energy consumption and therefore the heat it generates. " "Also if you have ACPI (Advanced Configuration and Power Interface) " "configured, then FreeBSD can also put the CPU into a low power mode." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2875 #, no-wrap msgid "Who is scratching in my memory banks??" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2879 msgid "" "_Q._ Is there anything \"odd\" that FreeBSD does when compiling the kernel " "which would cause the memory to make a scratchy sound? When compiling (and " "for a brief moment after recognizing the floppy drive upon startup, as " "well), a strange scratchy sound emanates from what appears to be the memory " "banks." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2883 msgid "" "_A._ Yes! You will see frequent references to \"daemons\" in the BSD " "documentation, and what most people do not know is that this refers to " "genuine, non-corporeal entities that now possess your computer. The " "scratchy sound coming from your memory is actually high-pitched whispering " "exchanged among the daemons as they best decide how to deal with various " "system administration tasks." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2888 msgid "" "If the noise gets to you, a good `fdisk /mbr` from DOS will get rid of them, " "but do not be surprised if they react adversely and try to stop you. In " "fact, if at any point during the exercise you hear the satanic voice of Bill " "Gates coming from the built-in speaker, take off running and do not ever " "look back! Freed from the counterbalancing influence of the BSD daemons, the " "twin demons of DOS and Windows(R) are often able to re-assert total control " "over your machine to the eternal damnation of your soul. Now that you know, " "given a choice you would probably prefer to get used to the scratchy noises, " "no?" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2890 #, no-wrap msgid "How many FreeBSD hackers does it take to change a lightbulb?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2893 msgid "One thousand, one hundred and sixty-nine:" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2895 msgid "Twenty-three to complain to -CURRENT about the lights being out;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2897 msgid "" "Four to claim that it is a configuration problem, and that such matters " "really belong on -questions;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2899 msgid "" "Three to submit PRs about it, one of which is misfiled under doc and " "consists only of \"it's dark\";" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2901 msgid "" "One to commit an untested lightbulb which breaks buildworld, then back it " "out five minutes later;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2903 msgid "" "Eight to flame the PR originators for not including patches in their PRs;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2905 msgid "Five to complain about buildworld being broken;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2907 msgid "" "Thirty-one to answer that it works for them, and they must have updated at a " "bad time;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2909 msgid "One to post a patch for a new lightbulb to -hackers;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2911 msgid "" "One to complain that he had patches for this three years ago, but when he " "sent them to -CURRENT they were just ignored, and he has had bad experiences " "with the PR system; besides, the proposed new lightbulb is non-reflexive;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2913 msgid "" "Thirty-seven to scream that lightbulbs do not belong in the base system, " "that committers have no right to do things like this without consulting the " "Community, and WHAT IS -CORE DOING ABOUT IT!?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2915 msgid "Two hundred to complain about the color of the bicycle shed;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2917 msgid "Three to point out that the patch breaks man:style[9];" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2919 msgid "Seventeen to complain that the proposed new lightbulb is under GPL;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2921 msgid "" "Five hundred and eighty-six to engage in a flame war about the comparative " "advantages of the GPL, the BSD license, the MIT license, the NPL, and the " "personal hygiene of unnamed FSF founders;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2923 msgid "Seven to move various portions of the thread to -chat and -advocacy;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2925 msgid "" "One to commit the suggested lightbulb, even though it shines dimmer than the " "old one;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2927 msgid "" "Two to back it out with a furious flame of a commit message, arguing that " "FreeBSD is better off in the dark than with a dim lightbulb;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2929 msgid "" "Forty-six to argue vociferously about the backing out of the dim lightbulb " "and demanding a statement from -core;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2931 msgid "" "Eleven to request a smaller lightbulb so it will fit their Tamagotchi if we " "ever decide to port FreeBSD to that platform;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2933 msgid "" "Seventy-three to complain about the SNR on -hackers and -chat and " "unsubscribe in protest;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2935 msgid "" "Thirteen to post \"unsubscribe\", \"How do I unsubscribe?\", or \"Please " "remove me from the list\", followed by the usual footer;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2937 msgid "" "One to commit a working lightbulb while everybody is too busy flaming " "everybody else to notice;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2939 msgid "" "Thirty-one to point out that the new lightbulb would shine 0.364% brighter " "if compiled with TenDRA (although it will have to be reshaped into a cube), " "and that FreeBSD should therefore switch to TenDRA instead of GCC;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2941 msgid "One to complain that the new lightbulb lacks fairings;" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2943 msgid "Nine (including the PR originators) to ask \"what is MFC?\";" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2945 msgid "" "Fifty-seven to complain about the lights being out two weeks after the bulb " "has been changed." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2947 msgid "_{nik} adds:_" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2949 msgid "_I was laughing quite hard at this._" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2951 msgid "" "_And then I thought, \"Hang on, shouldn't there be '1 to document it.' in " "that list somewhere?\"_" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2953 msgid "_And then I was enlightened :-)_" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2955 msgid "" "_{tabthorpe}_ says: \"None, _real_ FreeBSD hackers are not afraid of the " "dark!\"" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2957 #, no-wrap msgid "Where does data written to [.filename]#/dev/null# go?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2963 msgid "" "It goes into a special data sink in the CPU where it is converted to heat " "which is vented through the heatsink / fan assembly. This is why CPU " "cooling is increasingly important; as people get used to faster processors, " "they become careless with their data and more and more of it ends up in [." "filename]#/dev/null#, overheating their CPUs. If you delete [.filename]#/" "dev/null# (which effectively disables the CPU data sink) your CPU may run " "cooler but your system will quickly become constipated with all that excess " "data and start to behave erratically. If you have a fast network connection " "you can cool down your CPU by reading data out of [.filename]#/dev/random# " "and sending it off somewhere; however you run the risk of overheating your " "network connection and [.filename]#/# or angering your ISP, as most of the " "data will end up getting converted to heat by their equipment, but they " "generally have good cooling, so if you do not overdo it you should be OK." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2965 msgid "_Paul Robinson adds:_" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2971 msgid "" "There are other methods. As every good sysadmin knows, it is part of " "standard practice to send data to the screen of interesting variety to keep " "all the pixies that make up your picture happy. Screen pixies (commonly mis-" "typed or re-named as \"pixels\") are categorized by the type of hat they " "wear (red, green or blue) and will hide or appear (thereby showing the color " "of their hat) whenever they receive a little piece of food. Video cards " "turn data into pixie-food, and then send them to the pixies - the more " "expensive the card, the better the food, so the better behaved the pixies " "are. They also need constant stimulation - this is why screen savers exist." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2975 msgid "" "To take your suggestions further, you could just throw the random data to " "console, thereby letting the pixies consume it. This causes no heat to be " "produced at all, keeps the pixies happy and gets rid of your data quite " "quickly, even if it does make things look a bit messy on your screen." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2979 msgid "" "Incidentally, as an ex-admin of a large ISP who experienced many problems " "attempting to maintain a stable temperature in a server room, I would " "strongly discourage people sending the data they do not want out to the " "network. The fairies who do the packet switching and routing get annoyed by " "it as well." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2981 #, no-wrap msgid "My colleague sits at the computer too much, how can I prank her?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2984 msgid "Install package:games/sl[] and wait for her to mistype `sl` for `ls`." msgstr "" #. type: Title == #: documentation/content/en/books/faq/_index.adoc:2986 #, no-wrap msgid "Advanced Topics" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2989 #, no-wrap msgid "How can I learn more about FreeBSD's internals?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2992 msgid "See the extref:{arch-handbook}[FreeBSD Architecture Handbook]." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:2994 msgid "" "Additionally, much general UNIX(R) knowledge is directly applicable to " "FreeBSD." msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:2996 #, no-wrap msgid "How can I contribute to FreeBSD? What can I do to help?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3000 msgid "" "We accept all types of contributions: documentation, code, and even art. " "See the article on extref:{contributing}[Contributing to FreeBSD] for " "specific advice on how to do this." msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3002 msgid "And thanks for the thought!" msgstr "" #. type: Title === #: documentation/content/en/books/faq/_index.adoc:3004 #, no-wrap msgid "What are snapshots and releases?" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3008 msgid "" "There are currently {rel-numbranch} active/semi-active branches in the " -"FreeBSD http://svnweb.FreeBSD.org/base/[Subversion Repository]. (Earlier " -"branches are only changed very rarely, which is why there are only {rel-" -"numbranch} active branches of development):" +"FreeBSD http://cgit.FreeBSD.org/src/[Git Repository]. (Earlier branches are " +"only changed very rarely, which is why there are only {rel-numbranch} active " +"branches of development):" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3010 msgid "{rel2-releng} AKA {rel2-stable}" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3011 msgid "{rel-releng} AKA {rel-stable}" msgstr "" #. type: Plain text #: documentation/content/en/books/faq/_index.adoc:3012 msgid "{rel-head-releng} AKA _-CURRENT_ AKA {rel-head}" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3015 -msgid "" -"`HEAD` is not an actual branch tag. It is a symbolic constant for the " -"current, non-branched development stream known as _-CURRENT_." -msgstr "" - -#. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3017 +#: documentation/content/en/books/faq/_index.adoc:3014 msgid "" "Right now, _-CURRENT_ is the {rel-head-relx} development stream; the {rel-" "stable} branch, {rel-releng}, forked off from _-CURRENT_ in {rel-relengdate} " "and the {rel2-stable} branch, {rel2-releng}, forked off from _-CURRENT_ in " "{rel2-relengdate}." msgstr "" #. type: Title === -#: documentation/content/en/books/faq/_index.adoc:3019 +#: documentation/content/en/books/faq/_index.adoc:3016 #, no-wrap msgid "How can I make the most of the data I see when my kernel panics?" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3022 +#: documentation/content/en/books/faq/_index.adoc:3019 msgid "Here is typical kernel panic:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3038 +#: documentation/content/en/books/faq/_index.adoc:3035 #, no-wrap msgid "" "Fatal trap 12: page fault while in kernel mode\n" "fault virtual address = 0x40\n" "fault code = supervisor read, page not present\n" "instruction pointer = 0x8:0xf014a7e5\n" "stack pointer = 0x10:0xf4ed6f24\n" "frame pointer = 0x10:0xf4ed6f28\n" "code segment = base 0x0, limit 0xfffff, type 0x1b\n" " = DPL 0, pres 1, def32 1, gran 1\n" "processor eflags = interrupt enabled, resume, IOPL = 0\n" "current process = 80 (mount)\n" "interrupt mask =\n" "trap number = 12\n" "panic: page fault\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3043 +#: documentation/content/en/books/faq/_index.adoc:3040 msgid "" "This message is not enough. While the instruction pointer value is " "important, it is also configuration dependent as it varies depending on the " "kernel image. If it is a [.filename]#GENERIC# kernel image from one of the " "snapshots, it is possible for somebody else to track down the offending " "function, but for a custom kernel, only you can tell us where the fault " "occurred." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3045 +#: documentation/content/en/books/faq/_index.adoc:3042 msgid "To proceed:" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3050 +#: documentation/content/en/books/faq/_index.adoc:3047 msgid "" "Write down the instruction pointer value. Note that the `0x8:` part at the " "beginning is not significant in this case: it is the `0xf0xxxxxx` part that " "we want." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3051 +#: documentation/content/en/books/faq/_index.adoc:3048 msgid "When the system reboots, do the following:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3055 +#: documentation/content/en/books/faq/_index.adoc:3052 #, no-wrap msgid "% nm -n kernel.that.caused.the.panic | grep f0xxxxxx\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3060 +#: documentation/content/en/books/faq/_index.adoc:3057 msgid "" "where `f0xxxxxx` is the instruction pointer value. The odds are you will " "not get an exact match since the symbols in the kernel symbol table are for " "the entry points of functions and the instruction pointer address will be " "somewhere inside a function, not at the start. If you do not get an exact " "match, omit the last digit from the instruction pointer value and try again:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3064 +#: documentation/content/en/books/faq/_index.adoc:3061 #, no-wrap msgid "% nm -n kernel.that.caused.the.panic | grep f0xxxxx\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3070 +#: documentation/content/en/books/faq/_index.adoc:3067 msgid "" "If that does not yield any results, chop off another digit. Repeat until " "there is some sort of output. The result will be a possible list of " "functions which caused the panic. This is a less than exact mechanism for " "tracking down the point of failure, but it is better than nothing." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3074 +#: documentation/content/en/books/faq/_index.adoc:3071 msgid "" "However, the best way to track down the cause of a panic is by capturing a " "crash dump, then using man:kgdb[1] to generate a stack trace on the crash " "dump." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3076 +#: documentation/content/en/books/faq/_index.adoc:3073 msgid "In any case, the method is this:" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3080 +#: documentation/content/en/books/faq/_index.adoc:3077 msgid "" "Make sure that the following line is included in the kernel configuration " "file:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3084 +#: documentation/content/en/books/faq/_index.adoc:3081 #, no-wrap msgid "makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3087 +#: documentation/content/en/books/faq/_index.adoc:3084 msgid "Change to the [.filename]#/usr/src# directory:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3091 +#: documentation/content/en/books/faq/_index.adoc:3088 #, no-wrap msgid "# cd /usr/src\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3094 +#: documentation/content/en/books/faq/_index.adoc:3091 msgid "Compile the kernel:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3098 +#: documentation/content/en/books/faq/_index.adoc:3095 #, no-wrap msgid "# make buildkernel KERNCONF=MYKERNEL\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3101 +#: documentation/content/en/books/faq/_index.adoc:3098 msgid "Wait for man:make[1] to finish compiling." msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3105 +#: documentation/content/en/books/faq/_index.adoc:3102 #, no-wrap msgid "# make installkernel KERNCONF=MYKERNEL\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3108 +#: documentation/content/en/books/faq/_index.adoc:3105 msgid "Reboot." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3113 +#: documentation/content/en/books/faq/_index.adoc:3110 msgid "" "If `KERNCONF` is not included, the [.filename]#GENERIC# kernel will instead " "be built and installed." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3118 +#: documentation/content/en/books/faq/_index.adoc:3115 msgid "" "The man:make[1] process will have built two kernels. [.filename]#/usr/obj/" "usr/src/sys/MYKERNEL/kernel# and [.filename]#/usr/obj/usr/src/sys/MYKERNEL/" "kernel.debug#. [.filename]#kernel# was installed as [.filename]#/boot/" "kernel/kernel#, while [.filename]#kernel.debug# can be used as the source of " "debugging symbols for man:kgdb[1]." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3123 +#: documentation/content/en/books/faq/_index.adoc:3120 msgid "" "To capture a crash dump, edit [.filename]#/etc/rc.conf# and set `dumpdev` to " "point to either the swap partition or `AUTO`. This will cause the man:rc[8] " "scripts to use the man:dumpon[8] command to enable crash dumps. This " "command can also be run manually. After a panic, the crash dump can be " "recovered using man:savecore[8]; if `dumpdev` is set in [.filename]#/etc/rc." "conf#, the man:rc[8] scripts will run man:savecore[8] automatically and put " "the crash dump in [.filename]#/var/crash#." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3131 +#: documentation/content/en/books/faq/_index.adoc:3128 msgid "" "FreeBSD crash dumps are usually the same size as physical RAM. Therefore, " "make sure there is enough space in [.filename]#/var/crash# to hold the " "dump. Alternatively, run man:savecore[8] manually and have it recover the " "crash dump to another directory with more room. It is possible to limit the " "size of the crash dump by using `options MAXMEM=N` where _N_ is the size of " "kernel's memory usage in KBs. For example, for 1 GB of RAM, limit the " "kernel's memory usage to 128 MB, so that the crash dump size will be 128 MB " "instead of 1 GB." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3134 +#: documentation/content/en/books/faq/_index.adoc:3131 msgid "Once the crash dump has been recovered , get a stack trace as follows:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3139 +#: documentation/content/en/books/faq/_index.adoc:3136 #, no-wrap msgid "" "% kgdb /usr/obj/usr/src/sys/MYKERNEL/kernel.debug /var/crash/vmcore.0\n" "(kgdb) backtrace\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3146 +#: documentation/content/en/books/faq/_index.adoc:3143 msgid "" "Note that there may be several screens worth of information. Ideally, use " "man:script[1] to capture all of them. Using the unstripped kernel image " "with all the debug symbols should show the exact line of kernel source code " "where the panic occurred. The stack trace is usually read from the bottom " "up to trace the exact sequence of events that lead to the crash. man:" "kgdb[1] can also be used to print out the contents of various variables or " "structures to examine the system state at the time of the crash." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3150 +#: documentation/content/en/books/faq/_index.adoc:3147 msgid "" "If a second computer is available, man:kgdb[1] can be configured to do " "remote debugging, including setting breakpoints and single-stepping through " "the kernel code." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/faq/_index.adoc:3157 +#: documentation/content/en/books/faq/_index.adoc:3154 msgid "" "If `DDB` is enabled and the kernel drops into the debugger, a panic and a " "crash dump can be forced by typing `panic` at the `ddb` prompt. It may stop " "in the debugger again during the panic phase. If it does, type `continue` " "and it will finish the crash dump." msgstr "" #. type: Title === -#: documentation/content/en/books/faq/_index.adoc:3160 +#: documentation/content/en/books/faq/_index.adoc:3157 #, no-wrap msgid "Why has dlsym() stopped working for ELF executables?" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3164 +#: documentation/content/en/books/faq/_index.adoc:3161 msgid "" "The ELF toolchain does not, by default, make the symbols defined in an " "executable visible to the dynamic linker. Consequently `dlsym()` searches " "on handles obtained from calls to `dlopen(NULL, flags)` will fail to find " "such symbols." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3166 +#: documentation/content/en/books/faq/_index.adoc:3163 msgid "" "To search, using `dlsym()`, for symbols present in the main executable of a " "process, link the executable using the `--export-dynamic` option to the ELF " "linker (man:ld[1])." msgstr "" #. type: Title === -#: documentation/content/en/books/faq/_index.adoc:3168 +#: documentation/content/en/books/faq/_index.adoc:3165 #, no-wrap msgid "How can I increase or reduce the kernel address space on i386?" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3172 +#: documentation/content/en/books/faq/_index.adoc:3169 msgid "" "By default, the kernel address space is 1 GB (2 GB for PAE) for i386. When " "running a network-intensive server or using ZFS, this will probably not be " "enough." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3174 +#: documentation/content/en/books/faq/_index.adoc:3171 msgid "" "Add the following line to the kernel configuration file to increase " "available space and rebuild the kernel:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/faq/_index.adoc:3178 +#: documentation/content/en/books/faq/_index.adoc:3175 #, no-wrap msgid "options KVA_PAGES=N\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3182 +#: documentation/content/en/books/faq/_index.adoc:3179 msgid "" "To find the correct value of _N_, divide the desired address space size (in " "megabytes) by four. (For example, it is `512` for 2 GB.)" msgstr "" #. type: Title == -#: documentation/content/en/books/faq/_index.adoc:3184 +#: documentation/content/en/books/faq/_index.adoc:3181 #, no-wrap msgid "Acknowledgments" msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3188 +#: documentation/content/en/books/faq/_index.adoc:3185 msgid "" "This innocent little Frequently Asked Questions document has been written, " "rewritten, edited, folded, spindled, mutilated, eviscerated, contemplated, " "discombobulated, cogitated, regurgitated, rebuilt, castigated, and " "reinvigorated over the last decade, by a cast of hundreds if not thousands. " "Repeatedly." msgstr "" #. type: Plain text -#: documentation/content/en/books/faq/_index.adoc:3189 +#: documentation/content/en/books/faq/_index.adoc:3186 msgid "" "We wish to thank every one of the people responsible, and we encourage you " "to extref:{contributing}[join them] in making this FAQ even better." msgstr "" diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.po b/documentation/content/en/books/fdp-primer/editor-config/_index.po index b9e821d4d7..0883f46132 100644 --- a/documentation/content/en/books/fdp-primer/editor-config/_index.po +++ b/documentation/content/en/books/fdp-primer/editor-config/_index.po @@ -1,555 +1,555 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-04-20 20:56-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/editor-config/_index.adoc:1 #, no-wrap msgid "Configuration used in the texts editors in the FreeBSD Documentation Project" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:1 #, no-wrap -msgid "Chapter 12. Editor Configuration" +msgid "Chapter 13. Editor Configuration" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:13 #, no-wrap msgid "Editor Configuration" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:51 msgid "" "Adjusting your text editor configuration can make working on document files " "quicker and easier, and help documents conform to FDP guidelines." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:53 #, no-wrap msgid "Vim" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:57 msgid "" "Install from package:editors/vim[], or package:editors/vim-console[], then " "follow the configuration instructions in <>. More " "advanced users can use a proper linter like link:https://github.com/dense-" "analysis/ale[Ale] which can also act as a Vim link:https://langserver.org/" "[Language Server Protocol] client." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:59 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:326 #, no-wrap msgid "Use" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:62 msgid "" "Manual page writers can use the following keyboard shortcuts to reformat:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:64 msgid "" "Press kbd:[P] to reformat paragraphs or text that has been selected in " "Visual mode." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:65 msgid "Press kbd:[T] to replace groups of eight spaces with a tab." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:68 msgid "" "A linter named link:https://vale.sh[Vale] has been introduced to check " "grammatical and cosmetic errors on the documents. Vale has support for " "various editors and IDEs." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:71 msgid "" "Vale may already be installed as a dependency of the package:textproc/" "docproj[] meta-port. If not, install package:textproc/vale[] with:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:75 #, no-wrap msgid "$ pkg install vale\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:78 msgid "" "Install link:https://github.com/dense-analysis/ale[Ale] to integrate into " "package:editors/vim[], for using package:textproc/vale[]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:83 #, no-wrap msgid "" "% mkdir -p ~/.vim/pack/vendor/start\n" "% git clone --depth 1 https://github.com/dense-analysis/ale.git ~/.vim/pack/vendor/start/ale\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:86 msgid "" "Users who are using plugin managers for package:editors/vim[] do not need " "the above and should follow the instructions of that plugin manager to " "install link:https://github.com/dense-analysis/ale[Ale]." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:89 msgid "" "At this moment due to a bug in link:https://vale.sh[Vale] it is necessary to " "copy the link:https://vale.sh[Vale] configuration to the home directory. " "Considering the repository was cloned into [.filename]#~/doc# copy as " "following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:93 #, no-wrap msgid "% cp -R ~/doc/.vale* ~/\n" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:96 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:260 #, no-wrap msgid "Configuration" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:99 msgid "Edit [.filename]#~/.vimrc#, adding these lines to the end of the file:" msgstr "" #. type: Block title #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:101 #, no-wrap msgid "`~/.vimrc`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:107 #, no-wrap msgid "" "if has(\"autocmd\")\n" " au BufNewFile,BufRead *.adoc call Set_ADOC()\n" " au BufNewFile,BufRead *.[1-9] call Set_MAN()\n" "endif \" has(autocmd)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:112 #, no-wrap msgid "" "function Set_Highlights()\n" " \"match ExtraWhitespace /^\\s* \\s*\\|\\s\\+$/\n" " return 0\n" "endfunction \" Set_Highlights_Adoc()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:118 #, no-wrap msgid "" "function Set_Highlights_MAN()\n" " highlight default link OverLength ErrorMsg\n" " match OverLength /\\%71v.\\+/\n" " return 0\n" "endfunction \" Set_Highlights_MAN()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:124 #, no-wrap msgid "" "function ShowSpecial()\n" " setlocal list listchars=tab:>>,trail:*,eol:$\n" " hi def link nontext ErrorMsg\n" " return 0\n" "endfunction \" ShowSpecial()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:137 #, no-wrap msgid "" "function Set_COMMON()\n" " setlocal number\n" " setlocal shiftwidth=2\n" " setlocal tabstop=8\n" " setlocal softtabstop=2\n" " setlocal formatprg=\"fmt -p\"\n" " setlocal autoindent\n" " setlocal smartindent\n" " call ShowSpecial()\n" " call Set_Highlights()\n" " return 0\n" "endfunction \" Set_COMMON()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:144 #, no-wrap msgid "" "function Set_ADOC()\n" " setlocal syntax=asciidoc\n" " setlocal filetype=asciidoc\n" " call Set_COMMON()\n" " return 0\n" "endfunction \" Set_ADOC()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:157 #, no-wrap msgid "" "function Set_MAN()\n" " setlocal syntax=man\n" " setlocal filetype=man\n" " setlocal textwidth=70\n" " \" Rewrap paragraphs\n" " noremap P gqj\n" " \" Replace spaces with tabs\n" " noremap T :s/ /\\t/\n" " call Set_COMMON()\n" " call Set_Highlights_MAN()\n" " return 0\n" "endfunction \" Set_Man()\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:165 #, no-wrap msgid "" "let g:ale_fixers = {\n" "\\ '*': ['remove_trailing_lines', 'trim_whitespace'],\n" "\\}\n" "let g:ale_linters = {\n" "\\ 'asciidoc': ['vale'],\n" "\\}\n" "let g:ale_fix_on_save = 1\n" msgstr "" #. type: delimited block = 6 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:171 msgid "" "Above configuration will automatically remove trailing line, trailing space " "and multiple spaces which might display additional unwanted changes in `git " "diff` output. In such cases properly mention that in the commit log." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:174 #, no-wrap msgid "Emacs" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:177 msgid "Install from package:editors/emacs[] or package:editors/emacs-devel[]." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:179 #, no-wrap msgid "Validation" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:184 msgid "" "Emacs's nxml-mode uses compact relax NG schemas for validating XML. A " "compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included " "in the documentation repository. To configure nxml-mode to validate using " "this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these " "lines to the file:" msgstr "" #. type: Block title #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:186 #, no-wrap msgid "`~/.emacs.d/schema/schemas.xml`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:195 #, no-wrap msgid "" "\n" " \n" " \n" " \n" " \n" " \n" "\n" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:198 #, no-wrap msgid "Automated Proofreading with Flycheck and Igor" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:202 msgid "" "The link:https://www.flycheck.org/[Flycheck] package is available from link:" "https://melpa.org/[Milkypostman's Emacs Lisp Package Archive] (MELPA). If " "MELPA is not already in Emacs's packages-archives, it can be added by " "evaluating" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:206 #, no-wrap msgid "(add-to-list 'package-archives '(\"melpa\" . \"http://stable.melpa.org/packages/\") t)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:209 msgid "" "Add the line to Emacs's initialization file (one of [.filename]#~/.emacs#, [." "filename]#~/.emacs.el#, or [.filename]#~.emacs.d/init.el#) to make this " "change permanent." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:211 msgid "To install Flycheck, evaluate" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:215 #, no-wrap msgid "(package-install 'flycheck)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:218 msgid "Create a Flycheck checker for package:textproc/igor[] by evaluating" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:223 #, no-wrap msgid "" "(flycheck-define-checker igor\n" " \"FreeBSD Documentation Project sanity checker.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:230 #, no-wrap msgid "" "See URLs https://www.freebsd.org/docproj/ and\n" "http://www.freshports.org/textproc/igor/.\"\n" " :command (\"igor\" \"-X\" source-inplace)\n" " :error-parser flycheck-parse-checkstyle\n" " :modes (nxml-mode)\n" " :standard-input t)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:232 #, no-wrap msgid " (add-to-list 'flycheck-checkers 'igor 'append)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:235 msgid "" "Again, add these lines to Emacs's initialization file to make the changes " "permanent." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:237 #, no-wrap msgid "FreeBSD Documentation Specific Settings" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:240 msgid "" "To apply settings specific to the FreeBSD documentation project, create [." "filename]#.dir-locals.el# in the root directory of the documentation " "repository and add these lines to the file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:244 #, no-wrap msgid "" ";;; Directory Local Variables\n" ";;; For more information see (info \"(emacs) Directory Variables\")\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:252 #, no-wrap msgid "" "((nxml-mode\n" " (eval . (turn-on-auto-fill))\n" " (fill-column . 70)\n" " (eval . (require 'flycheck))\n" " (eval . (flycheck-mode 1))\n" " (flycheck-checker . igor)\n" " (eval . (add-to-list 'rng-schema-locating-files \"~/.emacs.d/schema/schemas.xml\"))))\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:255 #, no-wrap msgid "nano" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:258 msgid "Install from package:editors/nano[] or package:editors/nano-devel[]." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:264 msgid "" "Currently there is no adoc/asciidoc syntax highlight file with nano " "distribution. So let's create one from scratch and use an editor to create " "new file or add lines in the [.filename]#~/.nanorc# with these contents:" msgstr "" #. type: Block title #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:266 #, no-wrap msgid "`~/.nanorc`" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:316 #, no-wrap msgid "" "syntax \"asciidoc\" \"\\.(adoc|asc|asciidoc)$\"\n" "# main header\n" "color red \"^====+$\"\n" "# h1\n" "color red \"^==[[:space:]].*$\"\n" "color red \"^----+$\"\n" "# h2\n" "color magenta \"^===[[:space:]].*$\"\n" "color magenta \"^~~~~+$\"\n" "# h4\n" "color green \"^====[[:space:]].*$\"\n" "color green \"^\\^\\^\\^\\^+$\"\n" "# h5\n" "color brightblue \"^=====[[:space:]].*$\"\n" "color brightblue \"^\\+\\+\\+\\++$\"\n" "# attributes\n" "color brightgreen \":.*:\"\n" "color brightred \"\\{[a-z0-9]*\\}\"\n" "color red \"\\\\\\{[a-z0-9]*\\}\"\n" "color red \"\\+\\+\\+\\{[a-z0-9]*\\}\\+\\+\\+\"\n" "# Paragraph Title\n" "color yellow \"^\\..*$\"\n" "# source\n" "color magenta \"^\\[(source,.+|NOTE|TIP|IMPORTANT|WARNING|CAUTION)\\]\"\n" "# Other markup\n" "color yellow \".*[[:space:]]\\+$\"\n" "color yellow \"_[^_]+_\"\n" "color yellow \"\\*[^\\*]+\\*\"\n" "color yellow \"\\+[^\\+]+\\+\"\n" "color yellow \"`[^`]+`\"\n" "color yellow \"\\^[^\\^]+\\^\"\n" "color yellow \"~[^~]+~\"\n" "color yellow \"'[^']+'\"\n" "color cyan \"`{1,2}[^']+'{1,2}\"\n" "# bullets\n" "color brightmagenta \"^[[:space:]]*[\\*\\.-]{1,5}[[:space:]]\"\n" "# anchors\n" "color brightwhite \"\\[\\[.*\\]\\]\"\n" "color brightwhite \"<<.*>>\"\n" "# trailing whitespace\n" "color ,blue \"[[:space:]]+$\"\n" "# multiples of eight spaces at the start a line\n" "# (after zero or more tabs) should be a tab\n" "color ,blue \"^([TAB]*[ ]{8})+\"\n" "# tabs after spaces\n" "color ,yellow \"( )+TAB\"\n" "# highlight indents that have an odd number of spaces\n" "color ,red \"^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:319 msgid "Process the file to create embedded tabs:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:323 #, no-wrap msgid "% perl -i'' -pe 's/TAB/\\t/g' ~/.nanorc\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:329 msgid "Specify additional helpful options when running the editor:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:333 #, no-wrap msgid "% nano -AKipwz -T8 _index.adoc\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:336 msgid "" "Users of man:csh[1] can define an alias in [.filename]#~/.cshrc# to automate " "these options:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:340 #, no-wrap msgid "alias nano \"nano -AKipwz -r 70 -T8\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:343 msgid "After the alias is defined, the options will be added automatically:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/editor-config/_index.adoc:347 #, no-wrap msgid "% nano _index.adoc\n" msgstr "" diff --git a/documentation/content/en/books/fdp-primer/manual-pages/_index.po b/documentation/content/en/books/fdp-primer/manual-pages/_index.po index 29624f0e5e..f1ddcf8d3a 100644 --- a/documentation/content/en/books/fdp-primer/manual-pages/_index.po +++ b/documentation/content/en/books/fdp-primer/manual-pages/_index.po @@ -1,1182 +1,1182 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2022-02-01 10:28-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/manual-pages/_index.adoc:1 #, no-wrap msgid "How to work with the FreeBSD Manual Pages" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:1 #, no-wrap -msgid "Chapter 10. Manual Pages" +msgid "Chapter 11. Manual Pages" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:13 #, no-wrap msgid "Manual Pages" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:51 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:55 msgid "" "_Manual pages_, commonly shortened to _man pages_, were conceived as readily-" "available reminders for command syntax, device driver details, or " "configuration file formats. They have become an extremely valuable quick-" "reference from the command line for users, system administrators, and " "programmers." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:57 msgid "" "Although intended as reference material rather than tutorials, the EXAMPLES " "sections of manual pages often provide detailed use case." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:61 msgid "" "Manual pages are generally shown interactively by the man:man[1] command. " "When the user types `man ls`, a search is performed for a manual page " "matching `ls`. The first matching result is displayed." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:63 #, no-wrap msgid "Sections" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:67 msgid "" "Manual pages are grouped into _sections_. Each section contains manual " "pages for a specific category of documentation:" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:72 #, no-wrap msgid "Section Number" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:75 #, no-wrap msgid "Category" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:76 #, no-wrap msgid "1" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:78 #, no-wrap msgid "General Commands" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:79 #, no-wrap msgid "2" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:81 #, no-wrap msgid "System Calls" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:82 #, no-wrap msgid "3" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:84 #, no-wrap msgid "Library Functions" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:85 #, no-wrap msgid "4" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:87 #, no-wrap msgid "Kernel Interfaces" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:88 #, no-wrap msgid "5" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:90 #, no-wrap msgid "File Formats" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:91 #, no-wrap msgid "6" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:93 #, no-wrap msgid "Games" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:94 #, no-wrap msgid "7" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:96 #, no-wrap msgid "Miscellaneous" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:97 #, no-wrap msgid "8" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:99 #, no-wrap msgid "System Manager" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:100 #, no-wrap msgid "9" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:101 #, no-wrap msgid "Kernel Developer" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:104 #, no-wrap msgid "Markup" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:112 msgid "" "Various markup forms and rendering programs have been used for manual " "pages. FreeBSD has used man:groff[7] and the newer man:mandoc[1]. Most " "existing FreeBSD manual pages, and all new ones, use the man:mdoc[7] form of " "markup. This is a simple line-based markup that is reasonably expressive. " "It is mostly semantic: parts of text are marked up for what they are, rather " "than for how they should appear when rendered. There is some appearance-" "based markup which is usually best avoided." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:115 msgid "" "Manual page source is usually interpreted and displayed to the screen " "interactively. The source files can be ordinary text files or compressed " "with man:gzip[1] to save space." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:118 msgid "" "Manual pages can also be rendered to other formats, including PostScript for " "printing or PDF generation. See man:man[1]." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:120 #, no-wrap msgid "Manual Page Sections" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:125 msgid "" "Manual pages are composed of several standard sections. Each section has a " "title in upper case, and the sections for a particular type of manual page " "appear in a specific order. For a category 1 General Command manual page, " "the sections are:" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:130 #, no-wrap msgid "Section Name" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:133 #, no-wrap msgid "Description" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:134 #, no-wrap msgid "NAME" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:136 #, no-wrap msgid "Name of the command" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:137 #, no-wrap msgid "SYNOPSIS" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:139 #, no-wrap msgid "Format of options and arguments" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:140 #, no-wrap msgid "DESCRIPTION" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:142 #, no-wrap msgid "Description of purpose and usage" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:143 #, no-wrap msgid "ENVIRONMENT" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:145 #, no-wrap msgid "Environment settings that affect operation" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:146 #, no-wrap msgid "EXIT STATUS" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:148 #, no-wrap msgid "Error codes returned on exit" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:149 #, no-wrap msgid "EXAMPLES" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:151 #, no-wrap msgid "Examples of usage" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:152 #, no-wrap msgid "COMPATIBILITY" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:154 #, no-wrap msgid "Compatibility with other implementations" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:155 #, no-wrap msgid "SEE ALSO" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:157 #, no-wrap msgid "Cross-reference to related manual pages" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:158 #, no-wrap msgid "STANDARDS" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:160 #, no-wrap msgid "Compatibility with standards like POSIX" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:161 #, no-wrap msgid "HISTORY" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:163 #, no-wrap msgid "History of implementation" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:164 #, no-wrap msgid "BUGS" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:166 #, no-wrap msgid "Known bugs" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:167 #, no-wrap msgid "AUTHORS" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:168 #, no-wrap msgid "People who created the command or wrote the manual page." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:172 msgid "" "Some sections are optional, and the combination of sections for a specific " "type of manual page vary. Examples of the most common types are shown later " "in this chapter." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:174 #, no-wrap msgid "Macros" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:179 msgid "" "man:mdoc[7] markup is based on _macros_. Lines that begin with a dot " "contain macro commands, each two or three letters long. For example, " "consider this portion of the man:ls[1] manual page:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:208 #, no-wrap msgid "" ".Dd December 1, 2015 <.>\n" ".Dt LS 1\n" ".Sh NAME <.>\n" ".Nm ls\n" ".Nd list directory contents\n" ".Sh SYNOPSIS <.>\n" ".Nm <.>\n" ".Op Fl -libxo <.>\n" ".Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <.>\n" ".Op Fl D Ar format <.>\n" ".Op Ar <.>\n" ".Sh DESCRIPTION <.>\n" "For each operand that names a\n" ".Ar file\n" "of a type other than\n" "directory,\n" ".Nm\n" "displays its name as well as any requested,\n" "associated information.\n" "For each operand that names a\n" ".Ar file\n" "of type directory,\n" ".Nm\n" "displays the names of files contained\n" "within that directory, as well as any requested, associated\n" "information.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:211 msgid "A _Document date_ and _Document title_ are defined." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:213 msgid "" "A _Section header_ for the NAME section is defined. Then the _Name_ of the " "command and a one-line _Name description_ are defined." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:215 msgid "" "The SYNOPSIS section begins. This section describes the command-line " "options and arguments accepted." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:216 msgid "" "_Name_ (`.Nm`) has already been defined, and repeating it here just displays " "the defined value in the text." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:218 msgid "" "An _Optional_ _Flag_ called `-libxo` is shown. The `Fl` macro adds a dash " "to the beginning of flags, so this appears in the manual page as `--libxo`." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:219 msgid "A long list of optional single-character flags are shown." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:223 msgid "" "An optional `-D` flag is defined. If the `-D` flag is given, it must be " "followed by an _Argument_. The argument is a _format_, a string that tells " "man:ls[1] what to display and how to display it. Details on the format " "string are given later in the manual page." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:225 msgid "" "A final optional argument is defined. Since no name is specified for the " "argument, the default of `file ...` is used." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:226 msgid "The _Section header_ for the DESCRIPTION section is defined." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:228 msgid "" "When rendered with the command `man ls`, the result displayed on the screen " "looks like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:232 #, no-wrap msgid "LS(1) FreeBSD General Commands Manual LS(1)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:235 #, no-wrap msgid "" "NAME\n" " ls - list directory contents\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:239 #, no-wrap msgid "" "SYNOPSIS\n" " ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]\n" " [file ...]\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:246 #, no-wrap msgid "" "DESCRIPTION\n" " For each operand that names a file of a type other than directory, ls\n" " displays its name as well as any requested, associated information. For\n" " each operand that names a file of type directory, ls displays the names\n" " of files contained within that directory, as well as any requested,\n" " associated information.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:249 msgid "Optional values are shown inside square brackets." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:251 #, no-wrap msgid "Markup Guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:255 msgid "" "The man:mdoc[7] markup language is not very strict. For clarity and " "consistency, the FreeBSD Documentation project adds some additional style " "guidelines:" msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:256 #, no-wrap msgid "Only the first letter of macros is upper case" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:258 msgid "" "Always use upper case for the first letter of a macro and lower case for the " "remaining letters." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:259 #, no-wrap msgid "Begin new sentences on new lines" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:261 msgid "" "Start a new sentence on a new line, do not begin it on the same line as an " "existing sentence." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:262 #, no-wrap msgid "Update `.Dd` when making non-trivial changes to a manual page" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:266 msgid "" "The _Document date_ informs the reader about the last time the manual page " "was updated. It is important to update whenever non-trivial changes are " "made to the manual pages. Trivial changes like spelling or punctuation " "fixes that do not affect usage can be made without updating `.Dd`." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:267 #, no-wrap msgid "Give examples" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:272 msgid "" "Show the reader examples when possible. Even trivial examples are valuable, " "because what is trivial to the writer is not necessarily trivial to the " "reader. Three examples are a good goal. A trivial example shows the " "minimal requirements, a serious example shows actual use, and an in-depth " "example demonstrates unusual or non-obvious functionality." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:273 #, no-wrap msgid "Include the BSD license" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:276 msgid "" "Include the BSD license on new manual pages. The preferred license is " "available from the extref:{committers-guide}[Committer's Guide]." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:278 #, no-wrap msgid "Markup Tricks" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:281 msgid "Add a space before punctuation on a line with macros. Example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:289 #, no-wrap msgid "" ".Sh SEE ALSO\n" ".Xr geom 4 ,\n" ".Xr boot0cfg 8 ,\n" ".Xr geom 8 ,\n" ".Xr gptboot 8\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:295 msgid "" "Note how the commas at the end of the `.Xr` lines have been placed after a " "space. The `.Xr` macro expects two parameters to follow it, the name of an " "external manual page, and a section number. The space separates the " "punctuation from the section number. Without the space, the external links " "would incorrectly point to section `4,` or `8,`." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:297 #, no-wrap msgid "Important Macros" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:302 msgid "" "Some very common macros will be shown here. For more usage examples, see " "man:mdoc[7], man:groff_mdoc[7], or search for actual use in [.filename]#/usr/" "share/man/man*# directories. For example, to search for examples of the `." "Bd` _Begin display_ macro:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:306 #, no-wrap msgid "% find /usr/share/man/man* | xargs zgrep '.Bd'\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:309 #, no-wrap msgid "Organizational Macros" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:312 msgid "Some macros are used to define logical blocks of a manual page." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:317 #, no-wrap msgid "Organizational Macro" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:320 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:356 #, no-wrap msgid "Use" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:321 #, no-wrap msgid "`.Sh`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:325 #, no-wrap msgid "" "Section header.\n" "Followed by the name of the section, traditionally all upper case.\n" "Think of these as chapter titles." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:326 #, no-wrap msgid "`.Ss`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:330 #, no-wrap msgid "" "Subsection header.\n" "Followed by the name of the subsection.\n" "Used to divide a `.Sh` section into subsections." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:331 #, no-wrap msgid "`.Bl`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:333 #, no-wrap msgid "Begin list. Start a list of items." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:334 #, no-wrap msgid "`.El`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:336 #, no-wrap msgid "End a list." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:337 #, no-wrap msgid "`.Bd`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:340 #, no-wrap msgid "" "Begin display.\n" "Begin a special area of text, like an indented area." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:341 #, no-wrap msgid "`.Ed`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:342 #, no-wrap msgid "End display." msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:345 #, no-wrap msgid "Inline Macros" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:348 msgid "Many macros are used to mark up inline text." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:353 #, no-wrap msgid "Inline Macro" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:357 #, no-wrap msgid "`.Nm`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:360 #, no-wrap msgid "" "Name.\n" "Called with a name as a parameter on the first use, then used later without the parameter to display the name that has already been defined." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:361 #, no-wrap msgid "`.Pa`" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:363 #, no-wrap msgid "" "Path to a file.\n" "Used to mark up filenames and directory paths." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:366 #, no-wrap msgid "Sample Manual Page Structures" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:369 msgid "" "This section shows minimal desired man page contents for several common " "categories of manual pages." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:371 #, no-wrap msgid "Section 1 or 8 Command" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:374 msgid "The preferred basic structure for a section 1 or 8 command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:395 #, no-wrap msgid "" ".Dd August 25, 2017\n" ".Dt EXAMPLECMD 8\n" ".Os\n" ".Sh NAME\n" ".Nm examplecmd\n" ".Nd \"command to demonstrate section 1 and 8 man pages\"\n" ".Sh SYNOPSIS\n" ".Nm\n" ".Op Fl v\n" ".Sh DESCRIPTION\n" "The\n" ".Nm\n" "utility does nothing except demonstrate a trivial but complete\n" "manual page for a section 1 or 8 command.\n" ".Sh SEE ALSO\n" ".Xr exampleconf 5\n" ".Sh AUTHORS\n" ".An Firstname Lastname Aq Mt flastname@example.com\n" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:398 #, no-wrap msgid "Section 4 Device Driver" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:401 msgid "The preferred basic structure for a section 4 device driver:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:457 #, no-wrap msgid "" ".Dd August 25, 2017\n" ".Dt EXAMPLEDRIVER 4\n" ".Os\n" ".Sh NAME\n" ".Nm exampledriver\n" ".Nd \"driver to demonstrate section 4 man pages\"\n" ".Sh SYNOPSIS\n" "To compile this driver into the kernel, add this line to the\n" "kernel configuration file:\n" ".Bd -ragged -offset indent\n" ".Cd \"device exampledriver\"\n" ".Ed\n" ".Pp\n" "To load the driver as a module at boot, add this line to\n" ".Xr loader.conf 5 :\n" ".Bd -literal -offset indent\n" "exampledriver_load=\"YES\"\n" ".Ed\n" ".Sh DESCRIPTION\n" "The\n" ".Nm\n" "driver provides an opportunity to show a skeleton or template\n" "file for section 4 manual pages.\n" ".Sh HARDWARE\n" "The\n" ".Nm\n" "driver supports these cards from the aptly-named Nonexistent\n" "Technologies:\n" ".Pp\n" ".Bl -bullet -compact\n" ".It\n" "NT X149.2 (single and dual port)\n" ".It\n" "NT X149.8 (single port)\n" ".El\n" ".Sh DIAGNOSTICS\n" ".Bl -diag\n" ".It \"flashing green light\"\n" "Something bad happened.\n" ".It \"flashing red light\"\n" "Something really bad happened.\n" ".It \"solid black light\"\n" "Power cord is unplugged.\n" ".El\n" ".Sh SEE ALSO\n" ".Xr example 8\n" ".Sh HISTORY\n" "The\n" ".Nm\n" "device driver first appeared in\n" ".Fx 49.2 .\n" ".Sh AUTHORS\n" ".An Firstname Lastname Aq Mt flastname@example.com\n" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:460 #, no-wrap msgid "Section 5 Configuration File" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:463 msgid "The preferred basic structure for a section 5 configuration file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:479 #, no-wrap msgid "" ".Dd August 25, 2017\n" ".Dt EXAMPLECONF 5\n" ".Os\n" ".Sh NAME\n" ".Nm example.conf\n" ".Nd \"config file to demonstrate section 5 man pages\"\n" ".Sh DESCRIPTION\n" ".Nm\n" "is an example configuration file.\n" ".Sh SEE ALSO\n" ".Xr example 8\n" ".Sh AUTHORS\n" ".An Firstname Lastname Aq Mt flastname@example.com\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:482 #, no-wrap msgid "Testing" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:489 msgid "" "Testing a new manual page can be challenging. Fortunately there are some " "tools that can assist in the task. Some of them, like man:man[1], do not " "look in the current directory. It is a good idea to prefix the filename " "with `./` if the new manual page is in the current directory. An absolute " "path can also be used." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:491 msgid "Use man:mandoc[1]'s linter to check for parsing errors:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:495 #, no-wrap msgid "% mandoc -T lint ./mynewmanpage.8\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:498 msgid "Use package:textproc/igor[] to proofread the manual page:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:502 #, no-wrap msgid "% igor ./mynewmanpage.8\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:505 msgid "Use man:man[1] to check the final result of your changes:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:509 #, no-wrap msgid "% man ./mynewmanpage.8\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:512 msgid "" "You can use man:col[1] to filter the output of man:man[1] and get rid of the " "backspace characters before loading the result in your favorite editor for " "spell checking:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:516 #, no-wrap msgid "% man ./mynewmanpage.8 | col -b | vim -R -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:521 msgid "" "Spell-checking with fully-featured dictionaries is encouraged, and can be " "accomplished by using package:textproc/hunspell[] or package:textproc/" "aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-" "aspell[], respectively. For instance:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:525 #, no-wrap msgid "% aspell check --lang=en --mode=nroff ./mynewmanpage.8\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:528 #, no-wrap msgid "Example Manual Pages to Use as Templates" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:531 msgid "Some manual pages are suitable as in-depth examples." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:536 #, no-wrap msgid "Manual Page" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:539 #, no-wrap msgid "Path to Source Location" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:540 #, no-wrap msgid "man:cp[1]" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:542 #, no-wrap msgid "[.filename]#/usr/src/bin/cp/cp.1#" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:543 #, no-wrap msgid "man:vt[4]" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:545 #, no-wrap msgid "[.filename]#/usr/src/share/man/man4/vt.4#" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:546 #, no-wrap msgid "man:crontab[5]" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:548 #, no-wrap msgid "[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5#" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:549 #, no-wrap msgid "man:gpart[8]" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:550 #, no-wrap msgid "[.filename]#/usr/src/sbin/geom/class/part/gpart.8#" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:553 #, no-wrap msgid "Resources" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:556 msgid "Resources for manual page writers:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:558 msgid "man:man[1]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:559 msgid "man:mandoc[1]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:560 msgid "man:groff_mdoc[7]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:561 msgid "http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/manual-pages/_index.adoc:561 msgid "http://manpages.bsd.lv/history.html[History of UNIX Manpages]" msgstr "" diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.po b/documentation/content/en/books/fdp-primer/po-translations/_index.po index 7f14306f4d..282d21b676 100644 --- a/documentation/content/en/books/fdp-primer/po-translations/_index.po +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.po @@ -1,963 +1,917 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2022-02-01 10:28-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/po-translations/_index.adoc:1 #, no-wrap msgid "How to work with PO translation in the FreeBSD Documentation Project" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:1 #, no-wrap msgid "Chapter 9. PO Translations" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:13 #, no-wrap msgid "PO Translations" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:51 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:57 msgid "" "The http://www.gnu.org/software/gettext/[GNU gettext] system offers " "translators an easy way to create and maintain translations of documents. " "Translatable strings are extracted from the original document into a PO " "(Portable Object) file. Translated versions of the strings are entered with " "a separate editor. The strings can be used directly or built into a " "complete translated version of the original document." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:59 #, no-wrap msgid "Quick Start" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:63 msgid "" "The procedure shown in crossref:overview[overview-quick-start,Quick Start] " "is assumed to have already been performed. The `TRANSLATOR` option is " "required and already enabled by default in the package:textproc/docproj[] " "port." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:65 msgid "" "This example shows the creation of a Spanish translation of the short extref:" "{leap-seconds}[Leap Seconds] article." msgstr "" #. type: Block title #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:70 #, no-wrap msgid "Procedure: Install a PO Editor" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:72 msgid "" "A PO editor is needed to edit translation files. This example uses package:" "editors/poedit[]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:76 #, no-wrap msgid "# pkg install poedit\n" msgstr "" #. type: Block title #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:82 #, no-wrap msgid "Procedure: Initial Setup" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:85 msgid "" "When a new translation is first created, the directory structure must be " "created or copied from the English original:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:90 msgid "" "Create a directory for the new translation. The English article source is in " "[.filename]#~/doc/documentation/content/en/articles/leap-seconds/#. The " "Spanish translation will go in [.filename]#~/doc/documentation/content/es/" "articles/leap-seconds/#. The path is the same except for the name of the " "language directory. The English article source is in [.filename]#~/doc/en/" "articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/" "doc/es/articles/leap-seconds/#. The path is the same except for the name of " "the language directory." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:94 #, no-wrap msgid "% mkdir ~/doc/documentation/content/es/articles/leap-seconds\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:97 msgid "" -"Copy the [.filename]#_index.adoc# from the original document into the " +"Copy the [.filename]#_index.po# from the original document into the " "translation directory:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:102 #, no-wrap msgid "" -"% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \\\n" +"% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.po \\\n" " ~/doc/documentation/content/es/articles/leap-seconds/\n" msgstr "" -#. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:108 -#, no-wrap -msgid "Procedure: Translation" -msgstr "" - #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:112 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:106 msgid "" -"Translating a document consists of two steps: extracting translatable " -"strings from the original document, and entering translations for those " -"strings. These steps are repeated until the translator feels that enough of " -"the document has been translated to produce a usable translated document." +"Suppose the document or language is also being translated via Weblate. In " +"that case, it is good to get the `.po` file from there and upload the " +"translation document back into the platform, centralizing the translating " +"efforts via Weblate to avoid rework." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:114 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:108 msgid "" -"Extract the translatable strings from the original English version into a PO " -"file:" +"See how to download the `.po` files in the crossref:weblate[weblate-" +"translating-offline,Translating Offline on Weblate] chapter." msgstr "" -#. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:127 +#. type: Block title +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:113 #, no-wrap -msgid "" -"% cd ~/doc\n" -"% po4a-gettextize \\\n" -" --format asciidoc \\\n" -" --option compat=asciidoctor \\\n" -" --option yfm_keys=title,part,description \\\n" -" --master \"documentation/content/en/articles/leap-seconds/_index.adoc\" \\\n" -" --master-charset \"UTF-8\" \\\n" -" --copyright-holder \"The FreeBSD Project\" \\\n" -" --package-name \"FreeBSD Documentation\" \\\n" -" --po \"documentation/content/es/articles/leap-seconds/_index.po\"\n" +msgid "Procedure: Translation" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:130 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:117 msgid "" -"Use a PO editor to enter translations in the PO file. There are several " +"Use a PO editor to enter translations in the PO file. There are several " "different editors available. [.filename]#poedit# from package:editors/" "poedit[] is shown here." msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:134 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:121 #, no-wrap msgid "% poedit documentation/content/es/articles/leap-seconds/_index.po\n" msgstr "" #. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:140 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:127 #, no-wrap msgid "Procedure: Generating a Translated Document" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:142 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:129 msgid "Generate the translated document:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:156 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:134 #, no-wrap msgid "" "% cd ~/doc\n" -"% po4a-translate \\\n" -" --format asciidoc \\\n" -" --option compat=asciidoctor \\\n" -" --option yfm_keys=title,part,description \\\n" -" --master \"documentation/content/en/articles/leap-seconds/_index.adoc\" \\\n" -" --master-charset \"UTF-8\" \\\n" -" --po \"documentation/content/es/articles/leap-seconds/_index.po\" \\\n" -" --localized \"documentation/content/es/articles/leap-seconds/_index.adoc\" \\\n" -" --localized-charset \"UTF-8\" \\\n" -" --keep 0\n" +"% ./tools/translate.sh documentation es articles/leap-seconds\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:159 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:137 msgid "" "The name of the generated document matches the name of the English original, " "usually [.filename]#_index.adoc#." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:161 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:139 msgid "" "Check the generated file by rendering it to HTML and viewing it with a web " "browser:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:166 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:144 #, no-wrap msgid "" "% cd ~/doc/documentation\n" "% make\n" msgstr "" #. type: Title == -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:170 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:148 #, no-wrap msgid "Creating New Translations" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:175 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:153 msgid "" "The first step to creating a new translated document is locating or creating " "a directory to hold it. FreeBSD puts translated documents in a subdirectory " "named for their language and region in the format [.filename]#lang#. _lang_ " "is a two-character lowercase code." msgstr "" #. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:177 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:155 #, no-wrap msgid "Language Names" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:181 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:159 #, no-wrap msgid "Language" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:182 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:160 #, no-wrap msgid "Region" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:184 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:162 #, no-wrap msgid "Translated Directory Name" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:185 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:163 #, no-wrap msgid "English" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:186 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:164 #, no-wrap msgid "United States" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:188 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:166 #, no-wrap msgid "[.filename]#en#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:189 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:167 #, no-wrap msgid "Bengali" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:190 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:168 #, no-wrap msgid "Bangladesh" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:192 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:170 #, no-wrap msgid "[.filename]#bn-bd#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:193 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:171 #, no-wrap msgid "Danish" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:194 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:172 #, no-wrap msgid "Denmark" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:196 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:174 #, no-wrap msgid "[.filename]#da#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:197 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:175 #, no-wrap msgid "German" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:198 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:176 #, no-wrap msgid "Germany" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:200 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:178 #, no-wrap msgid "[.filename]#de#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:201 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:179 #, no-wrap msgid "Greek" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:202 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:180 #, no-wrap msgid "Greece" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:204 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:182 #, no-wrap msgid "[.filename]#el#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:205 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:183 #, no-wrap msgid "Spanish" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:206 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:184 #, no-wrap msgid "Spain" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:208 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:186 #, no-wrap msgid "[.filename]#es#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:209 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:187 #, no-wrap msgid "French" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:210 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:188 #, no-wrap msgid "France" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:212 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:190 #, no-wrap msgid "[.filename]#fr#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:213 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:191 #, no-wrap msgid "Hungarian" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:214 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:192 #, no-wrap msgid "Hungary" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:216 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:194 #, no-wrap msgid "[.filename]#hu#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:217 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:195 #, no-wrap msgid "Italian" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:218 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:196 #, no-wrap msgid "Italy" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:220 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:198 #, no-wrap msgid "[.filename]#it#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:221 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:199 #, no-wrap msgid "Japanese" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:222 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:200 #, no-wrap msgid "Japan" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:224 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:202 #, no-wrap msgid "[.filename]#ja#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:225 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:203 #, no-wrap msgid "Korean" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:226 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:204 #, no-wrap msgid "Korea" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:228 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:206 #, no-wrap msgid "[.filename]#ko#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:229 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:207 #, no-wrap msgid "Mongolian" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:230 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:208 #, no-wrap msgid "Mongolia" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:232 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:210 #, no-wrap msgid "[.filename]#mn#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:233 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:211 #, no-wrap msgid "Dutch" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:234 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:212 #, no-wrap msgid "Netherlands" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:236 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:214 #, no-wrap msgid "[.filename]#nl#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:237 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:215 #, no-wrap msgid "Polish" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:238 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:216 #, no-wrap msgid "Poland" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:240 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:218 #, no-wrap msgid "[.filename]#pl#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:241 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:219 #, no-wrap msgid "Portuguese" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:242 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:220 #, no-wrap msgid "Brazil" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:244 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:222 #, no-wrap msgid "[.filename]#pt-br#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:245 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:223 #, no-wrap msgid "Russian" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:246 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:224 #, no-wrap msgid "Russia" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:248 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:226 #, no-wrap msgid "[.filename]#ru#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:249 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:227 #, no-wrap msgid "Turkish" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:250 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:228 #, no-wrap msgid "Turkey" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:252 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:230 #, no-wrap msgid "[.filename]#tr#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:253 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:257 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:231 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:235 #, no-wrap msgid "Chinese" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:254 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:232 #, no-wrap msgid "China" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:256 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:234 #, no-wrap msgid "[.filename]#zh-cn#" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:258 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:236 #, no-wrap msgid "Taiwan" msgstr "" #. type: Table -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:259 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:237 #, no-wrap msgid "[.filename]#zh-tw#" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:265 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:243 msgid "" "The translations are in subdirectories of the main documentation directory, " "here assumed to be [.filename]#~/doc/documentation/# as shown in crossref:" "overview[overview-quick-start, Quick Start]. For example, German " "translations are located in [.filename]#~/doc/documentation/content/de/#, " "and French translations are in [.filename]#~/doc/documentation/content/fr/#." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:267 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:245 msgid "" "Each language directory contains separate subdirectories named for the type " "of documents, usually [.filename]#articles/# and [.filename]#books/#." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:271 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:249 msgid "" "Combining these directory names gives the complete path to an article or " "book. For example, the French translation of the NanoBSD article is in [." "filename]#~/doc/documentation/content/fr/articles/nanobsd/#, and the " "Mongolian translation of the Handbook is in [.filename]#~/doc/documentation/" "content/mn/books/handbook/#." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:274 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:252 msgid "" "A new language directory must be created when translating a document to a " "new language. If the language directory already exists, only a subdirectory " "in the [.filename]#articles/# or [.filename]#books/# directory is needed." msgstr "" #. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:276 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:254 #, no-wrap msgid "Creating a Spanish Translation of the Porter's Handbook" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:281 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:259 msgid "" "Create a new Spanish translation of the extref:{porters-handbook}[Porter's " "Handbook]. The original is a book in [.filename]#~/doc/documentation/" "content/en/books/porters-handbook/#." msgstr "" #. type: delimited block = 6 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:286 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:264 msgid "" "The Spanish language books directory [.filename]#~/doc/documentation/content/" "es/books/# already exists, so only a new subdirectory for the Porter's " "Handbook is needed:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:291 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:269 #, no-wrap msgid "" "% cd ~/doc/documentation/content/es/books\n" "% mkdir porters-handbook\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:294 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:272 msgid "Copy the content from the original book:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:299 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:277 #, no-wrap msgid "" "% cd porters-handbook\n" "% cp -R ~/doc/documentation/content/en/books/porters-handbook/* .\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:302 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:280 msgid "" "Now the document structure is ready for the translator to begin translating " "with `po4a` command." msgstr "" #. type: Title == -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:306 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:284 #, no-wrap msgid "Translating" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:311 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:289 msgid "" "The gettext system greatly reduces the number of things that must be tracked " "by a translator. Strings to be translated are extracted from the original " "document into a PO file. Then a PO editor is used to enter the translated " "versions of each string." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:313 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:291 msgid "" "The FreeBSD PO translation system does not overwrite PO files, so the " "extraction step can be run at any time to update the PO file." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:318 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:296 msgid "" "A PO editor is used to edit the file. package:editors/poedit[] is shown in " "these examples because it is simple and has minimal requirements. Other PO " "editors offer features to make the job of translating easier. The Ports " "Collection offers several of these editors, including package:devel/" "gtranslator[]." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:321 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:299 msgid "" "It is important to preserve the PO file. It contains all of the work that " "translators have done." msgstr "" -#. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:323 -#, no-wrap -msgid "Translating the Porter's Handbook to Spanish" -msgstr "" - -#. type: delimited block = 6 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:330 -msgid "Change to the base directory and update all PO files." -msgstr "" - -#. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:343 -#, no-wrap -msgid "" -"% cd ~/doc\n" -"% po4a-gettextize \\\n" -" --format asciidoc \\\n" -" --option compat=asciidoctor \\\n" -" --option yfm_keys=title,part,description \\\n" -" --master \"documentation/content/en/books/porters-handbook/_index.adoc\" \\\n" -" --master-charset \"UTF-8\" \\\n" -" --copyright-holder \"The FreeBSD Project\" \\\n" -" --package-name \"FreeBSD Documentation\" \\\n" -" --po \"documentation/content/es/books/porters-handbook/_index.po\"\n" -msgstr "" - #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:346 -msgid "Enter translations using a PO editor:" -msgstr "" - -#. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:350 -#, no-wrap -msgid "% poedit documentation/content/es/books/porters-handbook/_index.po\n" -msgstr "" - -#. type: delimited block = 6 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:354 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:304 msgid "" -"These steps are necessary for all `.adoc` files, excluding `chapters-order." -"adoc` and `toc-*.adoc`." +"Translating documents online proves to be the easiest method for document " +"translation on FreeBSD, as it allows multiple users to collaborate on the " +"same file, distributing the workload effectively. For more details, please " +"refer to the next chapter, crossref:weblate[weblate-introduction,Weblate " +"Translations]." msgstr "" #. type: Title == -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:358 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:307 #, no-wrap msgid "Tips for Translators" msgstr "" #. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:361 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:365 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:310 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:314 #, no-wrap msgid "Preserving AsciiDoc macros" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:364 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:313 msgid "Preserve AsciiDoc macros that are shown in the English original." msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:369 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:318 msgid "English original:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:375 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:324 #, no-wrap msgid "" "msgid \"\"\n" "\"This example shows the creation of a Spanish translation of the short \"\n" "\"extref:{leap-seconds}[Leap Seconds] article.\"\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:378 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:327 msgid "Spanish translation:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:384 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:333 #, no-wrap msgid "" "msgid \"\"\n" "\"Este ejemplo muestra la creación de un artículo con poco contenido como el artículo \"\n" "\"extref:{leap-seconds}[Leap Seconds].\"\n" msgstr "" #. type: Title === -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:389 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:338 #, no-wrap msgid "Preserving Spaces" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:393 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:342 msgid "" "Preserve existing spaces at the beginning and end of strings to be " "translated. The translated version must have these spaces also." msgstr "" #. type: Title === -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:395 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:344 #, no-wrap msgid "Verbatim Tags" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:398 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:347 msgid "The contents of some tags should be copied verbatim, not translated:" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:400 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:349 msgid "`man:man[1]`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:401 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:350 msgid "`package:package[]`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:402 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:351 msgid "`link`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:403 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:352 msgid "`image`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:404 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:353 msgid "`include`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:405 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:354 msgid "`Admonitions`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:406 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:355 msgid "`id's`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:407 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:356 msgid "`Heading tags`" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:408 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:357 msgid "`source`" msgstr "" #. type: Title == -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:410 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:359 #, no-wrap msgid "Building a Translated Document" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:416 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:365 msgid "" "A translated version of the original document can be created at any time. " "Any untranslated portions of the original will be included in English in the " "resulting document. Most PO editors have an indicator that shows how much " "of the translation has been completed. This makes it easy for the " "translator to see when enough strings have been translated to make building " "the final document worthwhile." msgstr "" +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:367 +msgid "" +"The Weblate chapter provides a complete example of how to crossref:" +"weblate[weblate-building,Build the Translated Document]." +msgstr "" + #. type: Title == -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:418 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:369 #, no-wrap msgid "Submitting the New Translation" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:422 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:373 msgid "" "Prepare the new translation files for submission. This includes adding the " "files to the version control system, setting additional properties on them, " "then creating a diff for submission." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:424 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:375 msgid "" "The diff files created by these examples can be attached to a https://bugs." "freebsd.org/bugzilla/enter_bug.cgi?product=Documentation[documentation bug " "report] or https://reviews.freebsd.org/[code review]." msgstr "" #. type: Block title -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:426 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:377 #, no-wrap msgid "Spanish Translation of the NanoBSD Article" msgstr "" #. type: delimited block = 6 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:433 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:384 msgid "" "Create a diff of the new files from the [.filename]#~/doc/# base directory " "so the full path is shown with the filenames. This helps committers identify " "the target language directory." msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:438 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:389 #, no-wrap msgid "" "% cd ~/doc\n" "% git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff\n" msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/books/fdp-primer/po-translations/_index.adoc:393 +msgid "" +"The Weblate chapter provides a complete example of how to crossref:" +"weblate[weblate-submitting-translations,Submit the New Translation]." +msgstr "" diff --git a/documentation/content/en/books/fdp-primer/see-also/_index.po b/documentation/content/en/books/fdp-primer/see-also/_index.po index 29ba532727..cd7cd25910 100644 --- a/documentation/content/en/books/fdp-primer/see-also/_index.po +++ b/documentation/content/en/books/fdp-primer/see-also/_index.po @@ -1,119 +1,119 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2022-08-07 10:35-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/see-also/_index.adoc:1 #, no-wrap msgid "More information about the FreeBSD Documentation Project" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:1 #, no-wrap -msgid "Chapter 14. See Also" +msgid "Chapter 15. See Also" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:13 #, no-wrap msgid "See Also" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:52 msgid "" "This document is deliberately not an exhaustive discussion of AsciiDoc and " "the FreeBSD Documentation Project. For more information about these, you " "are encouraged to see the following web sites." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:54 #, no-wrap msgid "The FreeBSD Documentation Project" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:57 msgid "" "link:https://www.FreeBSD.org/docproj/[The FreeBSD Documentation Project web " "pages]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:58 msgid "extref:{handbook}[The FreeBSD Handbook]" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:60 #, no-wrap msgid "Hugo" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:63 msgid "link:https://gohugo.io/[Hugo]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:64 msgid "link:https://gohugo.io/documentation/[Hugo documentation]" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:66 #, no-wrap msgid "AsciiDoctor" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:69 msgid "link:https://asciidoctor.org/[AsciiDoctor]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:70 msgid "link:https://docs.asciidoctor.org/[AsciiDoctor Documentation Portal]" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:72 #, no-wrap msgid "HTML" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:75 msgid "link:http://www.w3.org/[The World Wide Web Consortium]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:76 msgid "link:https://dev.w3.org/html5/spec-LC/[The HTML 5 specification]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:77 msgid "link:https://www.w3.org/Style/CSS/specs.en.html[CSS specification]" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/see-also/_index.adoc:77 msgid "link:https://sass-lang.com/[Sass]" msgstr "" diff --git a/documentation/content/en/books/fdp-primer/trademarks/_index.po b/documentation/content/en/books/fdp-primer/trademarks/_index.po index d5788e45d2..83a99ae8e4 100644 --- a/documentation/content/en/books/fdp-primer/trademarks/_index.po +++ b/documentation/content/en/books/fdp-primer/trademarks/_index.po @@ -1,157 +1,157 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-01-21 20:00-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/trademarks/_index.adoc:1 #, no-wrap msgid "Guidelines for trademarks in the FreeBSD Documentation Project" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:1 #, no-wrap -msgid "Chapter 13. Trademarks" +msgid "Chapter 14. Trademarks" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:13 #, no-wrap msgid "Trademarks" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:51 msgid "" "For all documents on the FreeBSD Documentation Project, citing registered " "trademarks is necessary and other trademarks is customary, and that is a " "requirement for every writer and contributor." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:53 #, no-wrap msgid "Trademark Symbols" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:58 msgid "" "Append a trademark symbol ((TM), (R), or other) to the first occurrence of " "the trademarked name, and always when using logos. Use the extref:{fdp-" "primer}/writing-style/#writing-style-special-characters[equivalent ASCII " "sequence], which will be rendered as the actual Unicode character. Also, " "write the trademarked name following its trademark guidelines." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:60 msgid "" "When in doubt, research the trademark owner's website, the product's " "website, and or the link:https://www.uspto.gov/trademarks[United States " "Patent and Trademark Office trademark search website]." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:62 #, no-wrap msgid "Trademark Citing" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:65 msgid "" "The FreeBSD Documentation Project provides a template for citing trademarks, " "which also avoids duplicating trademarks in the documents." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:67 msgid "" "First, look for the trademark in the link:https://cgit.freebsd.org/doc/tree/" "documentation/themes/beastie/i18n/en.toml#n328[Copyright section in the " "project's template], then add it to the trademarks tag on the `Front Matter` " "section of the document, located at the beginning of each document." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:69 msgid "" "The following is an example of the `Front Matter` of the extref:" "{contributing}[Contributing to FreeBSD] article:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:71 #, no-wrap msgid "---\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:81 #, no-wrap msgid "" "title: Contributing to FreeBSD\n" "authors:\n" " - author: Jordan Hubbard\n" " - author: Sam Lawrance\n" " - author: Mark Linimon\n" "description: How to contribute to the FreeBSD Project\n" "trademarks: [\"freebsd\", \"ieee\", \"general\"]\n" "weight: 15\n" "tags: [\"Contributing\", \"FreeBSD\", \"Non-Programmer Tasks\", \"Programmer Tasks\"]\n" "---\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:85 msgid "" "The trademark tags `freebsd`, `ieee`, and `general` will be automatically " "rendered when building the document like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:88 #, no-wrap msgid "FreeBSD is a registered trademark of the FreeBSD Foundation.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:90 #, no-wrap msgid "IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical and Electronics Engineers, Inc. in the United States.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:92 #, no-wrap msgid "Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:96 msgid "" "If a trademark is not present in the project's template, it must be " "submitted. Any developer or contributor can update the trademarks." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/trademarks/_index.adoc:97 msgid "" "The `freebsd` and `general` trademark tags are usually present in all " "documents." msgstr "" diff --git a/documentation/content/en/books/fdp-primer/weblate/_index.po b/documentation/content/en/books/fdp-primer/weblate/_index.po new file mode 100644 index 0000000000..d439ca1e95 --- /dev/null +++ b/documentation/content/en/books/fdp-primer/weblate/_index.po @@ -0,0 +1,1073 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \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/books/fdp-primer/weblate/_index.adoc:1 +#, no-wrap +msgid "How to join the FreeBSD translators team and translate online on Weblate" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:1 +#, no-wrap +msgid "Chapter 10. Weblate Translations" +msgstr "" + +#. type: Title = +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:13 +#, no-wrap +msgid "Weblate Translations" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:51 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:55 +msgid "" +"This chapter describes some basic steps for joining the FreeBSD translators " +"team, translating online on Weblate or offline, and some simple suggestions " +"on translating, proofreading, and testing. It's focused on the translation " +"part." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:57 +msgid "" +"The original documents (articles and books) are in the " +"{main-site}[documentation portal]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:59 +msgid "" +"https://weblate.org/en/[Weblate] is web-based open-source software focused " +"on localization; the FreeBSD project runs a local instance." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:61 +#, no-wrap +msgid "How to Become a FreeBSD Translator" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:64 +msgid "" +"Following are simple steps to start translating articles and books of the " +"FreeBSD Documentation Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:66 +msgid "" +"Create an account on the https://translate-dev.freebsd.org/[FreeBSD Weblate " +"instance] with an email address or your GitHub account." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:67 +msgid "Subscribe to the {freebsd-translators}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:71 +msgid "" +"Introduce yourself and ask to join a language team. If the language team " +"does not exist, ask to create it. The self-introduction is essential. It " +"raises your chances of being approved for write access." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:72 +msgid "Login to https://translate-dev.freebsd.org/[Weblate] with the new account." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:73 +msgid "Find the language team and choose an initial document to translate." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:75 +msgid "" +"Create a Bugzilla account to submit the translations after finishing a " +"document. The Documentation project is also accepting GitHub Pull Requests " +"with translation submissions." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:79 +msgid "" +"All translation files and documents must follow " +"https://www.freebsd.org/copyright/freebsd-doc-license/[The FreeBSD " +"Documentation License]; if this is unacceptable, please do not sign up or " +"send any patches or translations." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:82 +#, no-wrap +msgid "Introduce Yourself" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:86 +msgid "" +"Please provide a brief self-introduction on the {freebsd-translators} to " +"initiate the process of granting access. This will enable a language " +"coordinator or administrator to provide the necessary permissions for the " +"new user of Weblate to start translating." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:88 +msgid "Following is an example of how such an email could look." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:92 +#, no-wrap +msgid "Subject: Self-Introduction: Name and language\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:104 +#, no-wrap +msgid "" +"Name: Name (use preferred name)\n" +"Location: City, country (optional)\n" +"Login: username or email (essential)\n" +"Language: Language to translate (essential)\n" +"Profession or student status: (optional)\n" +"About You: (free format -- info which you feel comfortable sharing with\n" +" others: company, school, other affiliation, historical qualifications, " +"other\n" +" projects you have worked on, level and type of computer skills, other " +"relevant skills,\n" +" etc.)\n" +"You and the FreeBSD Project: (free format: other FreeBSD projects of\n" +" interest, comments, etc.)\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:107 +#, no-wrap +msgid "Login to Weblate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:110 +msgid "Open https://translate-dev.freebsd.org/[] and `Sign in`." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:111 +#, no-wrap +msgid "Weblate Login" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:111 +#, no-wrap +msgid "weblate-login.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:114 +msgid "Use a username, email address, or GitHub account to log in." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:117 +msgid "" +"The user profile contains your preferences, name, and email address. The " +"name and address will be used in commits; keep this information accurate." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:121 +msgid "" +"On the FreeBSD Weblate instance, all translations will be committed to " +"https://github.com/freebsd/freebsd-doc-translate[freebsd-doc-translate] (an " +"intermediate repository on GitHub), not directly to " +"https://github.com/freebsd/freebsd-doc[freebsd-doc]. Translators must take " +"the PO gettext files (`.po`), converting them to `.adoc` and submit it via " +"https://bugs.freebsd.org/bugzilla/[Bugzilla] or " +"https://github.com/freebsd/freebsd-doc/pulls[GitHub] to get the translated " +"document published or updated in the documentation portal. See more in the " +"following sections." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:123 +msgid "" +"Weblate will commit daily, at least to `freebsd-doc-translate`, if any new " +"strings are translated." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:125 +#, no-wrap +msgid "Find a Language Team to Join In" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:128 +msgid "" +"Click `Projects`, choose `Documentation`, then click `Languages`, and see " +"all the available languages." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:129 +#, no-wrap +msgid "Weblate Languages" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:129 +#, no-wrap +msgid "weblate-languages.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:132 +msgid "" +"Note that some languages and translated documents already exist in the " +"documentation portal and repositories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:135 +msgid "" +"If the desired language for translation is not available in Weblate, please " +"contact the https://www.freebsd.org/docproj/translations/[language " +"coordinators] before asking to create a new language. If there is no " +"answer, then write to the {doceng}." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:137 +#, no-wrap +msgid "Translating Online on Weblate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:140 +msgid "" +"Translating documents online proves to be the easiest method for document " +"translation on FreeBSD, as it allows users to collaborate on the same file, " +"distributing the workload." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:142 +msgid "" +"Once a coordinator or administrator grants access to a specific language for " +"a username, the save button will be enabled, so that this user can start " +"translating." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:143 +#, no-wrap +msgid "Weblate Documents" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:143 +#, no-wrap +msgid "weblate-documents.webp" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:144 +#, no-wrap +msgid "Weblate Translate" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:144 +#, no-wrap +msgid "weblate-translate.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:150 +msgid "" +"Weblate has a set of links that lead to actual translation. The translation " +"is further divided into individual checks, like `Untranslated` or `Needing " +"review`. If the whole document is translated without any error, `All " +"translations` link is still available in case a review is necessary. " +"Alternatively, the search field can be used to find a specific string or " +"term." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:152 +msgid "" +"In the " +"https://docs.weblate.org/en/latest/user/translating.html#translation-projects[Weblate " +"documentation], there is more info about translations, like keyboard " +"shortcuts and other tips about the translation tool." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:154 +#, no-wrap +msgid "Translating Offline" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:158 +msgid "" +"Weblate on FreeBSD uses PO gettext files for translations. Users familiar " +"with PO gettext files that want to translate offline can download and upload " +"the translations through the document page on Weblate by clicking in the " +"`Files` section." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:159 +#, no-wrap +msgid "Weblate Offline" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:159 +#, no-wrap +msgid "weblate-offline.webp" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:162 +#, no-wrap +msgid "Translation based on Automatic Suggestions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:165 +msgid "" +"Languages using Weblate before the migration to Hugo/Asciidoctor can use " +"this feature from Weblate to save time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:168 +msgid "" +"This feature from Weblate uses the Translation Memory generated by the other " +"components and projects on the same server. The former Weblate translations " +"are hosted on the same server as read-only for that." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:171 +msgid "" +"Strings that match `100/100` in similarity can be copied and saved " +"directly. Other strings will need at least minor adjustment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:173 +msgid "Some examples:" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:174 +#, no-wrap +msgid "Weblate Automatic Suggestions 01" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:174 +#, no-wrap +msgid "weblate_automatic_suggestion_01.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:179 +msgid "" +"With the migration to Hugo/Asciidoctor, documents use UTF-8. Some HTML " +"entities should be replaced. Some strings, such as links, require changes " +"to markup." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:180 +#, no-wrap +msgid "Weblate Automatic Suggestions 02" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:180 +#, no-wrap +msgid "weblate_automatic_suggestion_02.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:183 +msgid "Links:" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:184 +#, no-wrap +msgid "Weblate Automatic Suggestions 03" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:184 +#, no-wrap +msgid "weblate_automatic_suggestion_03.webp" +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:187 +#, no-wrap +msgid "Proofreading and Weblate Quality Checks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:191 +msgid "" +"The document dashboard `Project/Language/Document` shows the translation " +"status and string status for that document. This page is handy for " +"proofreading and quality checks." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:192 +#, no-wrap +msgid "Weblate Revision 01" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:192 +#, no-wrap +msgid "weblate-revision1.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:195 +msgid "" +"In this example, two strings are missing the full stop; following that link " +"will show only those strings to be revised/translated." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:196 +#, no-wrap +msgid "Weblate Revision 02" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:196 +#, no-wrap +msgid "weblate-revision2.webp" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:199 +msgid "" +"Translators and reviewers often value observing translated strings in " +"context." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:201 +#, no-wrap +msgid "Building the Translated Document" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:205 +msgid "" +"The project does not use continuous integration and continuous delivery to " +"build translations. There are studies to make it available." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:210 +msgid "" +"The following example uses GitHub, as Weblate is also on GitHub. Note that " +"this repository is a read-only mirror, but Pull Requests are accepted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:213 +msgid "To build the translation locally, follow these steps:" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:218 +#, no-wrap +msgid "Procedure: Clone the necessary repositories" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:220 +msgid "Clone the `freebsd-doc` repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:224 +#, no-wrap +msgid "% git clone https://github.com/freebsd/freebsd-doc.git ~/freebsd-doc\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:227 +msgid "Clone the `freebsd-doc-translate` repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:231 +#, no-wrap +msgid "" +"% git clone https://github.com/freebsd/freebsd-doc-translate.git " +"~/freebsd-doc-translate\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:238 +#, no-wrap +msgid "Procedure: Copy a translation file to `freebsd-doc`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:242 +msgid "" +"With both repositories in place, copy the translation from " +"`freebsd-doc-translate` to `freebsd-doc`. Example of the Committer's Guide " +"article translation in Spanish." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:247 +#, no-wrap +msgid "" +"% cp " +"~/freebsd-doc-translate/documentation/content/es/articles/committers-guide/_index.po " +"\\\n" +"~/freebsd-doc/documentation/content/es/articles/committers-guide/\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:254 +#, no-wrap +msgid "Procedure: Convert a translation file (`.po`) to `.adoc`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:257 +msgid "Go to the root of `freebsd-doc`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:261 +#, no-wrap +msgid "% cd ~/freebsd-doc\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:264 +msgid "Translate (convert) the `.po` file to `.adoc`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:268 +#, no-wrap +msgid "% ./tools/translate.sh documentation es articles/committers-guide\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:271 +msgid "" +"By default: only files with more than eighty percent of strings translated " +"will be converted to `.adoc`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:273 +msgid "To ignore that limit:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:277 +#, no-wrap +msgid "" +"% KEEP_ENV=0 ./tools/translate.sh documentation es " +"articles/committers-guide\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:284 +msgid "" +"Some documents, like books, have many PO gettext files. Always copy all of " +"them when translating and building. Files that weren't translated will be " +"converted with the source (English) strings." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:289 +msgid "" +"The directory structure is fundamental. Always follow the English document " +"directory structure." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:295 +#, no-wrap +msgid "Procedure: Build the translated document" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:298 +msgid "Last, the building part." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:300 +msgid "" +"Enter the documentation directory because there is no need to build the " +"FreeBSD website." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:304 +#, no-wrap +msgid "% cd documentation\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:308 +msgid "" +"And build the documentation. Note that `en` is always added by default when " +"building any other language." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:312 +#, no-wrap +msgid "% DOC_LANG=es make\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:317 +msgid "" +"This command will build only the English and Spanish documents of the " +"FreeBSD documentation portal. The output will be in the [.filename]#public# " +"directory; open that in a browser. Note that some index files can redirect " +"the browser to the online page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:319 +msgid "" +"Another good option is to build and serve the content with Hugo's internal " +"webserver:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:323 +#, no-wrap +msgid "% DOC_LANG=es make run\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:326 +msgid "" +"By default, the webserver listens on `localhost`; To override this behavior, " +"specify the desired IP address in the `BIND` parameter value." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:330 +#, no-wrap +msgid "% DOC_LANG=es make run BIND=192.168.15.10\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:333 +msgid "" +"This builds and serves the content with Hugo's internal webserver and lets " +"it open, and if any file changes, it rebuilds them automatically." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:336 +msgid "" +"To make any necessary adjustments in the translation, follow the steps below " +"to re-sync all components:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:338 +msgid "Fix the translation string on https://translate-dev.freebsd.org/[Weblate]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:339 +msgid "Force Weblate to commit the changes on `Document/Manage/Commit` section." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:340 +msgid "" +"Sync the local Weblate repository `freebsd-doc-translate` with a `git pull " +"origin main` command." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:341 +msgid "Copy the translation again to `freebsd-doc`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:342 +msgid "Convert the translation to .adoc with the `./tools/translate.sh` script." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:343 +msgid "" +"Hugo will rebuild the file and not build the entire set if `make run` was " +"used; or re-execute `make`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:347 +msgid "" +"Follow the previous steps as many times as is necessary until the document " +"is ready to be published." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:350 +msgid "" +"The crossref:doc-build[doc-build-rendering,Documentation Build Process] " +"chapter includes information about rendering to HTML and PDF." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:352 +#, no-wrap +msgid "Submitting Translations" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:355 +msgid "" +"Example of submitting an update to the Brazilian Portuguese article " +"Committer's Guide." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:361 +#, no-wrap +msgid "Check the repository" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:365 +msgid "" +"After following the steps in crossref:weblate[weblate-building,Building the " +"Translated Document], go to the root of `freebsd-doc` and preview what's to " +"be committed. For an overview of files to be changed, and differences in " +"file content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:370 +#, no-wrap +msgid "" +"% git status\n" +"% git diff\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:373 +msgid "" +"Review the output, and if any files unrelated to the Committer's Guide " +"translation update were changed or added, take the appropriate action of " +"reverting or removing them, respectively, before proceeding further." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:375 +msgid "" +"Always include the PO gettext file (`.po`) and the translated document in " +"Hugo/Asciidoctor (`.adoc`)." +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:381 +#, no-wrap +msgid "Create a new branch and commit" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:384 +msgid "" +"Create another branch to separate the work, which will help with future " +"updates in the local repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:388 +#, no-wrap +msgid "% git checkout -b committers-guide_pt-br\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:391 +msgid "Register the local commit." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:396 +#, no-wrap +msgid "" +"% git add .\n" +"% git commit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:399 +msgid "Example of commit messages for translations:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:403 +#, no-wrap +msgid "pt-br/committers-guide: Sync with en XXXXXXX\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:406 +msgid "" +"Where `XXXXXXX` is the man:git[1] revision stored in the Weblate repository " +"[.filename]#~/freebsd-doc-translate/revision.txt#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:408 +msgid "If it is the first translation of an article:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:412 +#, no-wrap +msgid "Add Korean translation of Leap Seconds article\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:417 +msgid "" +"A message will be displayed after the commit if man:git[1] has not been " +"configured previously. Please follow the instructions and provide the name " +"and email address used on Weblate. This step is crucial to proper crediting " +"of contributors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:419 +msgid "Then check the entire commit, review changes, and author name and email." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:423 +#, no-wrap +msgid "% git show\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:430 +#, no-wrap +msgid "Generate a patch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:433 +msgid "Next, generate a man:git-format-patch[1] file." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:438 +#, no-wrap +msgid "" +"% git format-patch main\n" +"0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:442 +msgid "" +"Attach the patch " +"[.filename]#0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch# to a " +"problem report in https://bugs.freebsd.org/bugzilla/[FreeBSD Bugzilla]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:444 +msgid "Include the following information in the report:" +msgstr "" + +#. type: Block title +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:446 +#, no-wrap +msgid "Bugzilla Fields" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:450 +#, no-wrap +msgid "Field" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:452 +#, no-wrap +msgid "Value" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:453 +#, no-wrap +msgid "*product*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:455 +#, no-wrap +msgid "Documentation" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:456 +#, no-wrap +msgid "*Component*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:458 +#, no-wrap +msgid "Books & Articles" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:459 +#, no-wrap +msgid "*Summary*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:461 +#, no-wrap +msgid "Same as the local commit" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:462 +#, no-wrap +msgid "*Description*" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:466 +#, no-wrap +msgid "" +"State that instructions in this guide were followed, including proofreading " +"and other necessary steps.\n" +"Include things that may help with triage and progression of the report." +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:467 +#, no-wrap +msgid "*CC* (Optional)" +msgstr "" + +#. type: Table +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:468 +#, no-wrap +msgid "" +"If the language has coordinators, include their email addresses in the CC " +"field." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:471 +msgid "" +"For people familiar with man:git[1] and GitHub: instead of submitting the " +"patch through https://bugs.freebsd.org/bugzilla/[Bugzilla], a " +"https://github.com/freebsd/freebsd-doc/pulls[GitHub pull request] can be " +"used (use the name and address that you use with Weblate)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:474 +msgid "" +"https://github.com/freebsd/freebsd-doc/ is a secondary mirror. Changes to " +"the `doc` tree can be made only by people who have a `doc` commit bit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:476 +msgid "" +"When translators keep sending good-quality patches, they can be nominated by " +"other committers to receive write-access (a extref:{committers-guide}[doc " +"commit bit, committer.types] for translations), a FreeBSD account, and " +"associated perks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:478 +msgid "" +"The list of extref:{contributors}[Additional FreeBSD Contributors, " +"contrib-additional] includes non-committers whose contributions are " +"committed to the `doc` tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:480 +msgid "If in doubt about any procedure, write to the {freebsd-translators}." +msgstr "" + +#. type: Title == +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:482 +#, no-wrap +msgid "FAQ (Frequently Asked Questions)" +msgstr "" + +#. type: Title === +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:485 +#, no-wrap +msgid "Is it necessary to translate all the Copyright messages?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/fdp-primer/weblate/_index.adoc:487 +msgid "" +"Every language team decides this for their language; in `pt-br` (Brazilian " +"Portuguese) team, it was decided not to translate those messages." +msgstr "" diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.po b/documentation/content/en/books/fdp-primer/writing-style/_index.po index 1e212933fe..8296448ba7 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.po +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.po @@ -1,883 +1,883 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-05-21 14:43-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/fdp-primer/writing-style/_index.adoc:1 #, no-wrap msgid "Writing Style and some conventions used in the FreeBSD Documentation Project" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:1 #, no-wrap -msgid "Chapter 11. Writing Style" +msgid "Chapter 12. Writing Style" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:13 #, no-wrap msgid "Writing Style" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:51 #, no-wrap msgid "Tips" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:57 msgid "" "Technical documentation can be improved by consistent use of several " "principles. Most of these can be classified into three goals: _be clear_, " "_be complete_, and _be concise_. These goals can conflict with each other. " "Good writing consists of a balance between them." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:59 #, no-wrap msgid "Be Clear" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:64 msgid "" "Clarity is extremely important. The reader may be a novice, or reading the " "document in a second language. Strive for simple, uncomplicated text that " "clearly explains the concepts." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:68 msgid "" "Avoid flowery or embellished speech, jokes, or colloquial expressions. " "Write as simply and clearly as possible. Simple text is easier to " "understand and translate." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:73 msgid "" "Keep explanations as short, simple, and clear as possible. Avoid empty " "phrases like \"in order to\", which usually just means \"to\". Avoid " "potentially patronizing words like \"basically\". Avoid Latin terms like " "\"i.e.,\" or \"cf.\", which may be unknown outside of academic or scientific " "groups." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:77 msgid "" "Write in a formal style. Avoid addressing the reader as \"you\". For " "example, say \"copy the file to [.filename]#/tmp#\" rather than \"you can " "copy the file to [.filename]#/tmp#\"." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:84 msgid "" "Give clear, correct, _tested_ examples. A trivial example is better than no " "example. A good example is better yet. Do not give bad examples, " "identifiable by apologies or sentences like \"but really it should never be " "done that way\". Bad examples are worse than no examples. Give good " "examples, because _even when warned not to use the example as shown_, the " "reader will usually just use the example as shown." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:87 msgid "" "Avoid _weasel words_ like \"should\", \"might\", \"try\", or \"could\". " "These words imply that the speaker is unsure of the facts, and create doubt " "in the reader." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:89 msgid "" "Similarly, give instructions as imperative commands: not \"you should do " "this\", but merely \"do this\"." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:91 #, no-wrap msgid "Be Complete" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:97 msgid "" "Do not make assumptions about the reader's abilities or skill level. Tell " "them what they need to know. Give links to other documents to provide " "background information without having to recreate it. Put yourself in the " "reader's place, anticipate the questions they will ask, and answer them." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:99 #, no-wrap msgid "Be Concise" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:104 msgid "" "While features should be documented completely, sometimes there is so much " "information that the reader cannot easily find the specific detail needed. " "The balance between being complete and being concise is a challenge. One " "approach is to have an introduction, then a \"quick start\" section that " "describes the most common situation, followed by an in-depth reference " "section." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:106 #, no-wrap msgid "Guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:109 msgid "" "To promote consistency between the myriad authors of the FreeBSD " "documentation, some guidelines have been drawn up for authors to follow." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:110 #, no-wrap msgid "Use American English Spelling" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:114 msgid "" "There are several variants of English, with different spellings for the same " "word. Where spellings differ, use the American English variant. \"color\", " "not \"colour\", \"rationalize\", not \"rationalise\", and so on." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:119 msgid "" "The use of British English may be accepted in the case of a contributed " "article, however the spelling must be consistent within the whole document. " "The other documents such as books, web site, manual pages, etc. must use " "American English." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:121 #, no-wrap msgid "Do not use contractions" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:125 msgid "" "Do not use contractions. Always spell the phrase out in full. \"Don't use " "contractions\" is wrong." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:127 msgid "" "Avoiding contractions makes for a more formal tone, is more precise, and is " "slightly easier for translators." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:128 #, no-wrap msgid "Use the serial comma" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:131 msgid "" "In a list of items within a paragraph, separate each item from the others " "with a comma. Separate the last item from the others with a comma and the " "word \"and\"." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:133 msgid "For example:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:135 msgid "This is a list of one, two and three items." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:137 msgid "" "Is this a list of three items, \"one\", \"two\", and \"three\", or a list of " "two items, \"one\" and \"two and three\"?" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:139 msgid "It is better to be explicit and include a serial comma:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:141 msgid "This is a list of one, two, and three items." msgstr "" #. type: Labeled list #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:141 #, no-wrap msgid "Avoid redundant phrases" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:144 msgid "" "Do not use redundant phrases. In particular, \"the command\", \"the file\", " "and \"man command\" are often redundant." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:146 msgid "For example, commands:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:148 msgid "Wrong: Use the `git` command to update sources." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:150 msgid "Right: Use `git` to update sources." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:152 msgid "Filenames:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:154 msgid "Wrong: ... in the filename [.filename]#/etc/rc.local#..." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:156 msgid "Right: ... in [.filename]#/etc/rc.local#..." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:158 msgid "" "Manual page references (the second example uses `citerefentry` with the man:" "csh[1] entity):" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:160 msgid "Wrong: See `man csh` for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:162 msgid "Right: See man:csh[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:164 msgid "" "For more information about writing style, see http://www.bartleby.com/141/" "[Elements of Style] by William Strunk." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:166 #, no-wrap msgid "Style Guide" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:169 msgid "" "To keep the source for the documentation consistent when many different " "people are editing it, please follow these style conventions." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:171 #, no-wrap msgid "One sentence per line" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:176 msgid "" "Use Semantic Line Breaks in the documentation, a technique called \"one " "sentence per line\". The idea of this technique is to help the users to " "write and read documentation. To get more information about this technique " "read the link:https://sembr.org/[Semantic Line Breaks] page." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:178 msgid "This is an example which does not use \"one sentence per line\"." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:181 #, no-wrap msgid "All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:184 msgid "And this is an example which uses the technique." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:188 #, no-wrap msgid "" "All human beings are born free and equal in dignity and rights.\n" "They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:191 #, no-wrap msgid "Acronyms" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:196 msgid "" "Acronyms should be defined the first time they appear in a document, as in: " "\"Network Time Protocol (NTP)\". After the acronym has been defined, use " "the acronym alone unless it makes more sense contextually to use the whole " "term. Acronyms are usually defined only once per chapter or per document." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:198 msgid "All acronyms should be enclosed using the ` character." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:200 #, no-wrap msgid "Special Character List" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:204 msgid "" "This list of special characters shows the correct syntax and the output when " "used in FreeBSD documentation. If a character is not on this list, ask " "about it on the {freebsd-doc}." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:209 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:264 #, no-wrap msgid "Name" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:210 #, no-wrap msgid "Syntax" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:213 #, no-wrap msgid "Rendered" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:214 #, no-wrap msgid "Copyright" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:215 #, no-wrap msgid "+(C)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:217 #, no-wrap msgid "(C)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:218 #, no-wrap msgid "Registered" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:219 #, no-wrap msgid "+(R)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:221 #, no-wrap msgid "(R)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:222 #, no-wrap msgid "Trademark" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:223 #, no-wrap msgid "+(TM)+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:225 #, no-wrap msgid "(TM)" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:226 #, no-wrap msgid "Em dash" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:227 #, no-wrap msgid "+--+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:229 #, no-wrap msgid "--" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:230 #, no-wrap msgid "Ellipses" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:231 #, no-wrap msgid "+...+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:233 #, no-wrap msgid "..." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:234 #, no-wrap msgid "Single right arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:235 #, no-wrap msgid "+->+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:237 #, no-wrap msgid "->" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:238 #, no-wrap msgid "Double right arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:239 #, no-wrap msgid "+=>+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:241 #, no-wrap msgid "=>" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:242 #, no-wrap msgid "Single left arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:243 #, no-wrap msgid "+<-+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:245 #, no-wrap msgid "<-" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:246 #, no-wrap msgid "Double left arrow" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:247 #, no-wrap msgid "+<=+" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:249 #, no-wrap msgid "<=" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:252 #, no-wrap msgid "Linting with Vale" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:257 msgid "" "To maintain clarity and consistency across all documentation and website " "pages, link:https://vale.sh[Vale] styles have been introduced in the " "documentation tree. link:https://vale.sh[Vale] is a powerful linter for " "writing customized rules and can be used in multiple scenarios. Currently " "link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD " "pipelines, and integrated into an editor of choice." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:259 msgid "" "The following table describes the current rule names and their respective " "severity." msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:266 #, no-wrap msgid "Severity" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:267 #, no-wrap msgid "FreeBSD.BrandTerms" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:269 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:287 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:293 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:296 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:299 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:302 #, no-wrap msgid "error" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:270 #, no-wrap msgid "FreeBSD.ConsciousLanguage" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:272 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:278 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:281 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:284 #, no-wrap msgid "warning" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:273 #, no-wrap msgid "FreeBSD.Contractions" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:275 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:290 #, no-wrap msgid "suggestion" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:276 #, no-wrap msgid "FreeBSD.EOLSpacing" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:279 #, no-wrap msgid "FreeBSD.Hang" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:282 #, no-wrap msgid "FreeBSD.Hyphens" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:285 #, no-wrap msgid "FreeBSD.Spacing" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:288 #, no-wrap msgid "FreeBSD.SuperfluousOptArgInLinks" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:291 #, no-wrap msgid "Vale.Avoid" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:294 #, no-wrap msgid "Vale.Repetition" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:297 #, no-wrap msgid "Vale.Spelling" msgstr "" #. type: Table #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:300 #, no-wrap msgid "Vale.Terms" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:305 #, no-wrap msgid "Current Vale Rules" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:311 msgid "" "FreeBSD.BrandTerms: According to the copyright rules of The FreeBSD " "Foundation, *freebsd* should be written as *FreeBSD*. Similarly, every " "major vendor and company has specific rules on writing their brand names and " "trademarks. Care should be taken to be respectful to the brand value of " "others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc. " "Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/" "BrandTerms.yml# in the `doc` repository." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:313 msgid "" "FreeBSD.ConsciousLanguage: This rule proposes use of conscious language so " "that sensitive words pointing to the color, age, race, or sexual orientation " "of people are avoided where possible." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:316 msgid "" "FreeBSD.Contractions: Contracted words should not be used. This rule avoids " "all contractions and suggests full words." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:318 msgid "" "FreeBSD.EOLSpacing: In most of the documents EOL spacing is present which is " "not the desirable situation." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:321 msgid "" "FreeBSD.Hang: `Hang` is often used to mean that the application has stopped " "responding. This rule proposes better wording." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:323 msgid "" "FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen " "which is wrong." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:325 msgid "" "FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye " "and this is addressed here." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:327 msgid "" "FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:" "` macros when the displayed text coincides with the URL." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:331 msgid "" "Vale.Avoid: Enforces the *DO NOT USE* vocabulary terms for The FreeBSD " "Project. If any word is found that should not be in the documentation, the " "word should be added to [.filename]#.vale/styles/Vocab/Terms/reject.txt# in " "the `doc` repository. The list is empty at the moment." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:334 msgid "" "Vale.Repetition: Same words are often typed twice when leaving the keyboard " "and rejoining the work again. This rule finds repeated words and warns the " "users." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:337 msgid "" "Vale.Spelling: At the moment there is a mix of en_US and en_GB spellings in " "the documentation and website. Vale comes with an in built dictionary from " "which uses strictly en_US and do not accept the en_GB variant of any words." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:341 msgid "" "Vale.Terms: Enforces the *PREFERRED* vocabulary terms for The FreeBSD " "Project. At the moment the list of terms is empty and the FreeBSD specific " "terms will be added gradually. If any word is found to be correct and not " "available in the dictionary the word should be added to the [.filename]#." "vale/styles/Vocab/Terms/accept.txt# in the `doc` repository." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:343 msgid "" "More rules will be introduced in the upcoming days when and where required." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:345 #, no-wrap msgid "Using Vale" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:349 msgid "" "link:https://vale.sh[Vale] can be used from the command line and from within " "an editor or IDE. package:textproc/vale[] can be installed as following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:353 #, no-wrap msgid "$ pkg install vale\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:356 #, no-wrap msgid "Using Vale on the command line" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:359 msgid "" "Assuming that the `doc` repository was cloned into [.filename]#~/doc# the " "following commands are required to run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:364 #, no-wrap msgid "" "% cd ~/doc\n" "% vale .\n" msgstr "" #. type: delimited block = 6 #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:370 msgid "" "link:https://vale.sh[Vale] is a CPU and memory intensive program due to the " "nature of the application and can take a while to show any output on the " "screen. A better way to run the application is on specific folders or files " "rather than the entire `doc` repository as that is already done in the CI " "pipeline." msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:373 #, no-wrap msgid "Using Vale in editors" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/writing-style/_index.adoc:377 msgid "" "link:https://vale.sh[Vale] works with major mainstream editors like package:" "editors/vim[], package:editors/emacs[], package:editors/vscode[]. At the " "moment the necessary configuration for package:editors/vim[] is described in " "crossref:editor-config[editor-config-vim, Vim]. A configuration for package:" "editors/emacs[] is being worked on." msgstr "" diff --git a/documentation/content/en/books/handbook/security/_index.po b/documentation/content/en/books/handbook/security/_index.po index 7b4ecd90ca..b9e9a619eb 100644 --- a/documentation/content/en/books/handbook/security/_index.po +++ b/documentation/content/en/books/handbook/security/_index.po @@ -1,5364 +1,5364 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-04-20 20:56-0300\n" +"POT-Creation-Date: 2023-06-19 21:07-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/handbook/security/_index.adoc:1 #, no-wrap msgid "Hundreds of standard practices have been authored about how to secure systems and networks, and as a user of FreeBSD, understanding how to protect against attacks and intruders is a must" msgstr "" #. type: YAML Front Matter: part #: documentation/content/en/books/handbook/security/_index.adoc:1 #, no-wrap msgid "Part III. System Administration" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/handbook/security/_index.adoc:1 #, no-wrap msgid "Chapter 15. Security" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/security/_index.adoc:14 #, no-wrap msgid "Security" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:52 #, no-wrap msgid "Synopsis" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:56 msgid "" "Security, whether physical or virtual, is a topic so broad that an entire " "industry has evolved around it. Hundreds of standard practices have been " "authored about how to secure systems and networks, and as a user of FreeBSD, " "understanding how to protect against attacks and intruders is a must." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:59 msgid "" "In this chapter, several fundamentals and techniques will be discussed. The " "FreeBSD system comes with multiple layers of security, and many more third " "party utilities may be added to enhance security." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:61 msgid "After reading this chapter, you will know:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:63 msgid "Basic FreeBSD system security concepts." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:64 msgid "The various crypt mechanisms available in FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:65 msgid "How to set up one-time password authentication." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:66 msgid "How to configure TCP Wrapper for use with man:inetd[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:67 msgid "How to set up Kerberos on FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:68 msgid "How to configure IPsec and create a VPN." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:69 msgid "How to configure and use OpenSSH on FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:70 msgid "How to use file system ACLs." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:71 msgid "" "How to use pkg to audit third party software packages installed from the " "Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:72 msgid "How to utilize FreeBSD security advisories." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:73 msgid "What Process Accounting is and how to enable it on FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:74 msgid "" "How to control user resources using login classes or the resource limits " "database." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:76 msgid "Before reading this chapter, you should:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:78 msgid "Understand basic FreeBSD and Internet concepts." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:81 msgid "" "Additional security topics are covered elsewhere in this Handbook. For " "example, Mandatory Access Control is discussed in crossref:mac[mac,Mandatory " "Access Control] and Internet firewalls are discussed in crossref:" "firewalls[firewalls,Firewalls]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:83 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:88 msgid "" "Security is everyone's responsibility. A weak entry point in any system " "could allow intruders to gain access to critical information and cause havoc " "on an entire network. One of the core principles of information security is " "the CIA triad, which stands for the Confidentiality, Integrity, and " "Availability of information systems." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:91 msgid "" "The CIA triad is a bedrock concept of computer security as customers and " "users expect their data to be protected. For example, a customer expects " "that their credit card information is securely stored (confidentiality), " "that their orders are not changed behind the scenes (integrity), and that " "they have access to their order information at all times (availability)." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:97 msgid "" "To provide CIA, security professionals apply a defense in depth strategy. " "The idea of defense in depth is to add several layers of security to prevent " "one single layer failing and the entire security system collapsing. For " "example, a system administrator cannot simply turn on a firewall and " "consider the network or system secure. One must also audit accounts, check " "the integrity of binaries, and ensure malicious tools are not installed. To " "implement an effective security strategy, one must understand threats and " "how to defend against them." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:100 msgid "" "What is a threat as it pertains to computer security? Threats are not " "limited to remote attackers who attempt to access a system without " "permission from a remote location. Threats also include employees, " "malicious software, unauthorized network devices, natural disasters, " "security vulnerabilities, and even competing corporations." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:104 msgid "" "Systems and networks can be accessed without permission, sometimes by " "accident, or by remote attackers, and in some cases, via corporate espionage " "or former employees. As a user, it is important to prepare for and admit " "when a mistake has led to a security breach and report possible issues to " "the security team. As an administrator, it is important to know of the " "threats and be prepared to mitigate them." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:110 msgid "" "When applying security to systems, it is recommended to start by securing " "the basic accounts and system configuration, and then to secure the network " "layer so that it adheres to the system policy and the organization's " "security procedures. Many organizations already have a security policy that " "covers the configuration of technology devices. The policy should include " "the security configuration of workstations, desktops, mobile devices, " "phones, production servers, and development servers. In many cases, " "standard operating procedures (SOPs) already exist. When in doubt, ask the " "security team." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:113 msgid "" "The rest of this introduction describes how some of these basic security " "configurations are performed on a FreeBSD system. The rest of this chapter " "describes some specific tools which can be used when implementing a security " "policy on a FreeBSD system." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:115 #, no-wrap msgid "Preventing Logins" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:120 msgid "" "In securing a system, a good starting point is an audit of accounts. Ensure " "that `root` has a strong password and that this password is not shared. " "Disable any accounts that do not need login access." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:124 msgid "" "To deny login access to accounts, two methods exist. The first is to lock " -"the account. This example locks the `toor` account:" +"the account. This example locks the `imani` account:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:128 #, no-wrap -msgid "# pw lock toor\n" +msgid "# pw lock imani\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:132 msgid "" "The second method is to prevent login access by changing the shell to [." "filename]#/usr/sbin/nologin#. Only the superuser can change the shell for " "other users:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:136 #, no-wrap -msgid "# chsh -s /usr/sbin/nologin toor\n" +msgid "# chsh -s /usr/sbin/nologin imani\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:139 msgid "" "The [.filename]#/usr/sbin/nologin# shell prevents the system from assigning " "a shell to the user when they attempt to login." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:141 #, no-wrap msgid "Permitted Account Escalation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:150 msgid "" "In some cases, system administration needs to be shared with other users. " "FreeBSD has two methods to handle this. The first one, which is not " "recommended, is a shared root password used by members of the `wheel` " "group. With this method, a user types `su` and enters the password for " "`wheel` whenever superuser access is needed. The user should then type " "`exit` to leave privileged access after finishing the commands that required " "administrative access. To add a user to this group, edit [.filename]#/etc/" "group# and add the user to the end of the `wheel` entry. The user must be " "separated by a comma character with no space." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:153 msgid "" "The second, and recommended, method to permit privilege escalation is to " "install the package:security/sudo[] package or port. This software provides " "additional auditing, more fine-grained user control, and can be configured " "to lock users into running only the specified privileged commands." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:156 msgid "" "After installation, use `visudo` to edit [.filename]#/usr/local/etc/" "sudoers#. This example creates a new `webadmin` group, adds the `trhodes` " "account to that group, and configures that group access to restart package:" "apache24[]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:162 #, no-wrap msgid "" "# pw groupadd webadmin -M trhodes -g 6000\n" "# visudo\n" "%webadmin ALL=(ALL) /usr/sbin/service apache24 *\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:165 #, no-wrap msgid "Password Hashes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:171 msgid "" "Passwords are a necessary evil of technology. When they must be used, they " "should be complex and a powerful hash mechanism should be used to encrypt " "the version that is stored in the password database. FreeBSD supports the " "DES, MD5, SHA256, SHA512, and Blowfish hash algorithms in its `crypt()` " "library. The default of SHA512 should not be changed to a less secure " "hashing algorithm, but can be changed to the more secure Blowfish algorithm." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:176 msgid "" "Blowfish is not part of AES and is not considered compliant with any Federal " "Information Processing Standards (FIPS). Its use may not be permitted in " "some environments." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:186 msgid "" "To determine which hash algorithm is used to encrypt a user's password, the " "superuser can view the hash for the user in the FreeBSD password database. " "Each hash starts with a symbol which indicates the type of hash mechanism " "used to encrypt the password. If DES is used, there is no beginning " "symbol. For MD5, the symbol is `$`. For SHA256 and SHA512, the symbol is " "`$6$`. For Blowfish, the symbol is `$2a$`. In this example, the password " "for `dru` is hashed using the default SHA512 algorithm as the hash starts " "with `$6$`. Note that the encrypted hash, not the password itself, is " "stored in the password database:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:191 #, no-wrap msgid "" "# grep dru /etc/master.passwd\n" "dru:$6$pzIjSvCAn.PBYQBA$PXpSeWPx3g5kscj3IMiM7tUEUSPmGexxta.8Lt9TGSi2lNQqYGKszsBPuGME0:1001:1001::0:0:dru:/usr/home/dru:/bin/csh\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:195 msgid "" "The hash mechanism is set in the user's login class. For this example, the " "user is in the `default` login class and the hash algorithm is set with this " "line in [.filename]#/etc/login.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:199 #, no-wrap msgid " :passwd_format=sha512:\\\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:202 msgid "" "To change the algorithm to Blowfish, modify that line to look like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:206 #, no-wrap msgid " :passwd_format=blf:\\\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:211 msgid "" "Then run `cap_mkdb /etc/login.conf` as described in <>. " "Note that this change will not affect any existing password hashes. This " "means that all passwords should be re-hashed by asking users to run `passwd` " "in order to change their password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:218 msgid "" "For remote logins, two-factor authentication should be used. An example of " "two-factor authentication is \"something you have\", such as a key, and " "\"something you know\", such as the passphrase for that key. Since OpenSSH " "is part of the FreeBSD base system, all network logins should be over an " "encrypted connection and use key-based authentication instead of passwords. " "For more information, refer to <>. Kerberos users may need to make " "additional changes to implement OpenSSH in their network. These changes are " "described in <>." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:220 #, no-wrap msgid "Password Policy Enforcement" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:224 msgid "" "Enforcing a strong password policy for local accounts is a fundamental " "aspect of system security. In FreeBSD, password length, password strength, " "and password complexity can be implemented using built-in Pluggable " "Authentication Modules (PAM)." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:227 msgid "" "This section demonstrates how to configure the minimum and maximum password " "length and the enforcement of mixed characters using the [." "filename]#pam_passwdqc.so# module. This module is enforced when a user " "changes their password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:230 msgid "" "To configure this module, become the superuser and uncomment the line " "containing `pam_passwdqc.so` in [.filename]#/etc/pam.d/passwd#. Then, edit " "that line to match the password policy:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:234 #, no-wrap msgid "password requisite pam_passwdqc.so min=disabled,disabled,disabled,12,10 similar=deny retry=3 enforce=users\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:244 msgid "" "This example sets several requirements for new passwords. The `min` setting " "controls the minimum password length. It has five values because this " "module defines five different types of passwords based on their complexity. " "Complexity is defined by the type of characters that must exist in a " "password, such as letters, numbers, symbols, and case. The types of " "passwords are described in man:pam_passwdqc[8]. In this example, the first " "three types of passwords are disabled, meaning that passwords that meet " "those complexity requirements will not be accepted, regardless of their " "length. The `12` sets a minimum password policy of at least twelve " "characters, if the password also contains characters with three types of " "complexity. The `10` sets the password policy to also allow passwords of at " "least ten characters, if the password contains characters with four types of " "complexity." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:247 msgid "" "The `similar` setting denies passwords that are similar to the user's " "previous password. The `retry` setting provides a user with three " "opportunities to enter a new password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:249 msgid "" "Once this file is saved, a user changing their password will see a message " "similar to the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:255 #, no-wrap msgid "" "% passwd\n" "Changing local password for trhodes\n" "Old Password:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:266 #, no-wrap msgid "" "You can now choose the new password.\n" "A valid password should be a mix of upper and lower case letters,\n" "digits and other characters. You can use a 12 character long\n" "password with characters from at least 3 of these 4 classes, or\n" "a 10 character long password containing characters from all the\n" "classes. Characters that form a common pattern are discarded by\n" "the check.\n" "Alternatively, if no one else can see your terminal now, you can\n" "pick this as your password: \"trait-useful&knob\".\n" "Enter new password:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:269 msgid "" "If a password that does not match the policy is entered, it will be rejected " "with a warning and the user will have an opportunity to try again, up to the " "configured number of retries." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:273 msgid "" "Most password policies require passwords to expire after so many days. To " "set a password age time in FreeBSD, set `passwordtime` for the user's login " "class in [.filename]#/etc/login.conf#. The `default` login class contains " "an example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:277 #, no-wrap msgid "# :passwordtime=90d:\\\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:280 msgid "" "So, to set an expiry of 90 days for this login class, remove the comment " "symbol (`+#+`), save the edit, and run `cap_mkdb /etc/login.conf`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:282 msgid "" "To set the expiration on individual users, pass an expiration date or the " "number of days to expiry and a username to `pw`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:286 #, no-wrap msgid "# pw usermod -p 30-apr-2015 -n trhodes\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:290 msgid "" "As seen here, an expiration date is set in the form of day, month, and " "year. For more information, see man:pw[8]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:292 #, no-wrap msgid "Detecting Rootkits" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:298 msgid "" "A _rootkit_ is any unauthorized software that attempts to gain `root` access " "to a system. Once installed, this malicious software will normally open up " "another avenue of entry for an attacker. Realistically, once a system has " "been compromised by a rootkit and an investigation has been performed, the " "system should be reinstalled from scratch. There is tremendous risk that " "even the most prudent security or systems engineer will miss something an " "attacker left behind." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:302 msgid "" "A rootkit does do one thing useful for administrators: once detected, it is " "a sign that a compromise happened at some point. But, these types of " "applications tend to be very well hidden. This section demonstrates a tool " "that can be used to detect rootkits, package:security/rkhunter[]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:305 msgid "" "After installation of this package or port, the system may be checked using " "the following command. It will produce a lot of information and will " "require some manual pressing of kbd:[ENTER]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:309 #, no-wrap msgid "# rkhunter -c\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:315 msgid "" "After the process completes, a status message will be printed to the " "screen. This message will include the amount of files checked, suspect " "files, possible rootkits, and more. During the check, some generic security " "warnings may be produced about hidden files, the OpenSSH protocol selection, " "and known vulnerable versions of installed software. These can be handled " "now or after a more detailed analysis has been performed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:320 msgid "" "Every administrator should know what is running on the systems they are " "responsible for. Third-party tools like rkhunter and package:sysutils/" "lsof[], and native commands such as `netstat` and `ps`, can show a great " "deal of information on the system. Take notes on what is normal, ask " "questions when something seems out of place, and be paranoid. While " "preventing a compromise is ideal, detecting a compromise is a must." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:322 #, no-wrap msgid "Binary Verification" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:326 msgid "" "Verification of system files and binaries is important because it provides " "the system administration and security teams information about system " "changes. A software application that monitors the system for changes is " "called an Intrusion Detection System (IDS)." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:330 msgid "" "FreeBSD provides native support for a basic IDS system. While the nightly " "security emails will notify an administrator of changes, the information is " "stored locally and there is a chance that a malicious user could modify this " "information in order to hide their changes to the system. As such, it is " "recommended to create a separate set of binary signatures and store them on " "a read-only, root-owned directory or, preferably, on a removable USB disk or " "remote rsync server." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:336 msgid "" "The built-in `mtree` utility can be used to generate a specification of the " "contents of a directory. A seed, or a numeric constant, is used to generate " "the specification and is required to check that the specification has not " "changed. This makes it possible to determine if a file or binary has been " "modified. Since the seed value is unknown by an attacker, faking or " "checking the checksum values of files will be difficult to impossible. The " "following example generates a set of SHA256 hashes, one for each system " "binary in [.filename]#/bin#, and saves those values to a hidden file in " "``root``'s home directory, [.filename]#/root/.bin_chksum_mtree#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:341 #, no-wrap msgid "" "# mtree -s 3483151339707503 -c -K cksum,sha256digest -p /bin > /root/.bin_chksum_mtree\n" "# mtree: /bin checksum: 3427012225\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:345 msgid "" "The _3483151339707503_ represents the seed. This value should be " "remembered, but not shared." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:347 msgid "" "Viewing [.filename]#/root/.bin_cksum_mtree# should yield output similar to " "the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:354 #, no-wrap msgid "" "# user: root\n" "# machine: dreadnaught\n" "# tree: /bin\n" "# date: Mon Feb 3 10:19:53 2014\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:370 #, no-wrap msgid "" "# .\n" "/set type=file uid=0 gid=0 mode=0555 nlink=1 flags=none\n" ". type=dir mode=0755 nlink=2 size=1024 \\\n" " time=1380277977.000000000\n" " \\133 nlink=2 size=11704 time=1380277977.000000000 \\\n" " cksum=484492447 \\\n" " sha256digest=6207490fbdb5ed1904441fbfa941279055c3e24d3a4049aeb45094596400662a\n" " cat size=12096 time=1380277975.000000000 cksum=3909216944 \\\n" " sha256digest=65ea347b9418760b247ab10244f47a7ca2a569c9836d77f074e7a306900c1e69\n" " chflags size=8168 time=1380277975.000000000 cksum=3949425175 \\\n" " sha256digest=c99eb6fc1c92cac335c08be004a0a5b4c24a0c0ef3712017b12c89a978b2dac3\n" " chio size=18520 time=1380277975.000000000 cksum=2208263309 \\\n" " sha256digest=ddf7c8cb92a58750a675328345560d8cc7fe14fb3ccd3690c34954cbe69fc964\n" " chmod size=8640 time=1380277975.000000000 cksum=2214429708 \\\n" " sha256digest=a435972263bf814ad8df082c0752aa2a7bdd8b74ff01431ccbd52ed1e490bbe7\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:374 msgid "" "The machine's hostname, the date and time the specification was created, and " "the name of the user who created the specification are included in this " "report. There is a checksum, size, time, and SHA256 digest for each binary " "in the directory." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:377 msgid "" "To verify that the binary signatures have not changed, compare the current " "contents of the directory to the previously generated specification, and " "save the results to a file. This command requires the seed that was used to " "generate the original specification:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:382 #, no-wrap msgid "" "# mtree -s 3483151339707503 -p /bin < /root/.bin_chksum_mtree >> /root/.bin_chksum_output\n" "# mtree: /bin checksum: 3427012225\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:387 msgid "" "This should produce the same checksum for [.filename]#/bin# that was " "produced when the specification was created. If no changes have occurred to " "the binaries in this directory, the [.filename]#/root/.bin_chksum_output# " "output file will be empty. To simulate a change, change the date on [." "filename]#/bin/cat# using `touch` and run the verification command again:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:395 #, no-wrap msgid "" "# touch /bin/cat\n" "# mtree -s 3483151339707503 -p /bin < /root/.bin_chksum_mtree >> /root/.bin_chksum_output\n" "# more /root/.bin_chksum_output\n" "cat changed\n" "\tmodification time expected Fri Sep 27 06:32:55 2013 found Mon Feb 3 10:28:43 2014\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:399 msgid "" "It is recommended to create specifications for the directories which contain " "binaries and configuration files, as well as any directories containing " "sensitive data. Typically, specifications are created for [.filename]#/" "bin#, [.filename]#/sbin#, [.filename]#/usr/bin#, [.filename]#/usr/sbin#, [." "filename]#/usr/local/bin#, [.filename]#/etc#, and [.filename]#/usr/local/" "etc#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:404 msgid "" "More advanced IDS systems exist, such as package:security/aide[]. In most " "cases, `mtree` provides the functionality administrators need. It is " "important to keep the seed value and the checksum output hidden from " "malicious users. More information about `mtree` can be found in man:" "mtree[8]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:406 #, no-wrap msgid "System Tuning for Security" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:411 msgid "" "In FreeBSD, many system features can be tuned using `sysctl`. A few of the " "security features which can be tuned to prevent Denial of Service (DoS) " "attacks will be covered in this section. More information about using " "`sysctl`, including how to temporarily change values and how to make the " "changes permanent after testing, can be found in crossref:" "config[configtuning-sysctl,“Tuning with sysctl(8)”]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:416 msgid "" "Any time a setting is changed with `sysctl`, the chance to cause undesired " "harm is increased, affecting the availability of the system. All changes " "should be monitored and, if possible, tried on a testing system before being " "used on a production system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:423 msgid "" "By default, the FreeBSD kernel boots with a security level of `-1`. This is " "called \"insecure mode\" because immutable file flags may be turned off and " "all devices may be read from or written to. The security level will remain " "at `-1` unless it is altered through `sysctl` or by a setting in the startup " "scripts. The security level may be increased during system startup by " "setting `kern_securelevel_enable` to `YES` in [.filename]#/etc/rc.conf#, and " "the value of `kern_securelevel` to the desired security level. See man:" "security[7] and man:init[8] for more information on these settings and the " "available security levels." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:428 msgid "" "Increasing the `securelevel` can break Xorg and cause other issues. Be " "prepared to do some debugging." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:435 msgid "" "The `net.inet.tcp.blackhole` and `net.inet.udp.blackhole` settings can be " "used to drop incoming SYN packets on closed ports without sending a return " "RST response. The default behavior is to return an RST to show a port is " "closed. Changing the default provides some level of protection against " "ports scans, which are used to determine which applications are running on a " "system. Set `net.inet.tcp.blackhole` to `2` and `net.inet.udp.blackhole` to " "`1`. Refer to man:blackhole[4] for more information about these settings." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:439 msgid "" "The `net.inet.icmp.drop_redirect` and `net.inet.ip.redirect` settings help " "prevent against _redirect attacks_. A redirect attack is a type of DoS " "which sends mass numbers of ICMP type 5 packets. Since these packets are " "not required, set `net.inet.icmp.drop_redirect` to `1` and set `net.inet.ip." "redirect` to `0`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:443 msgid "" "Source routing is a method for detecting and accessing non-routable " "addresses on the internal network. This should be disabled as non-routable " "addresses are normally not routable on purpose. To disable this feature, " "set `net.inet.ip.sourceroute` and `net.inet.ip.accept_sourceroute` to `0`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:447 msgid "" "When a machine on the network needs to send messages to all hosts on a " "subnet, an ICMP echo request message is sent to the broadcast address. " "However, there is no reason for an external host to perform such an action. " "To reject all external broadcast requests, set `net.inet.icmp.bmcastecho` to " "`0`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:449 msgid "Some additional settings are documented in man:security[7]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:451 #, no-wrap msgid "One-time Passwords" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:454 msgid "" "By default, versions of FreeBSD prior to 14.x include support for One-time " "Passwords In Everything (OPIE)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:461 msgid "" "OPIE is no longer considered secure and has been removed from FreeBSD -" "CURRENT; it will not be available from 14.x onwards. If you wish to use OPIE " "on versions of FreeBSD later than 13.x, the package:security/opie[] package " "or port is available, though not recommended." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:467 msgid "" "OPIE is designed to prevent replay attacks, in which an attacker discovers a " "user's password and uses it to access a system. Since a password is only " "used once in OPIE, a discovered password is of little use to an attacker. " "OPIE uses a secure hash and a challenge/response system to manage " "passwords. The FreeBSD implementation uses the MD5 hash by default." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:473 msgid "" "OPIE uses three different types of passwords. The first is the usual " "UNIX(R) or Kerberos password. The second is the one-time password which is " "generated by `opiekey`. The third type of password is the \"secret " "password\" which is used to generate one-time passwords. The secret " "password has nothing to do with, and should be different from, the UNIX(R) " "password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:482 msgid "" "There are two other pieces of data that are important to OPIE. One is the " "\"seed\" or \"key\", consisting of two letters and five digits. The other " "is the \"iteration count\", a number between 1 and 100. OPIE creates the " "one-time password by concatenating the seed and the secret password, " "applying the MD5 hash as many times as specified by the iteration count, and " "turning the result into six short English words which represent the one-time " "password. The authentication system keeps track of the last one-time " "password used, and the user is authenticated if the hash of the user-" "provided password is equal to the previous password. Since a one-way hash " "is used, it is impossible to generate future one-time passwords if a " "successfully used password is captured. The iteration count is decremented " "after each successful login to keep the user and the login program in sync. " "When the iteration count gets down to `1`, OPIE must be reinitialized." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:487 msgid "" "There are a few programs involved in this process. A one-time password, or " "a consecutive list of one-time passwords, is generated by passing an " "iteration count, a seed, and a secret password to man:opiekey[1]. In " "addition to initializing OPIE, man:opiepasswd[1] is used to change " "passwords, iteration counts, or seeds. The relevant credential files in [." "filename]#/etc/opiekeys# are examined by man:opieinfo[1] which prints out " "the invoking user's current iteration count and seed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:493 msgid "" "This section describes four different sorts of operations. The first is how " "to set up one-time-passwords for the first time over a secure connection. " "The second is how to use `opiepasswd` over an insecure connection. The " "third is how to log in over an insecure connection. The fourth is how to " "generate a number of keys which can be written down or printed out to use at " "insecure locations." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:494 #, no-wrap msgid "Initializing OPIE" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:497 msgid "" "To initialize OPIE for the first time, run this command from a secure " "location:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:508 #, no-wrap msgid "" "% opiepasswd -c\n" "Adding unfurl:\n" "Only use this method from the console; NEVER from remote. If you are using\n" "telnet, xterm, or a dial-in, type ^C now or exit with no password.\n" "Then run opiepasswd without the -c parameter.\n" "Using MD5 to compute responses.\n" "Enter new secret pass phrase:\n" "Again new secret pass phrase:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:511 #, no-wrap msgid "" "ID unfurl OTP key is 499 to4268\n" "MOS MALL GOAT ARM AVID COED\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:514 msgid "" "The `-c` sets console mode which assumes that the command is being run from " "a secure location, such as a computer under the user's control or an SSH " "session to a computer under the user's control." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:518 msgid "" "When prompted, enter the secret password which will be used to generate the " "one-time login keys. This password should be difficult to guess and should " "be different than the password which is associated with the user's login " "account. It must be between 10 and 127 characters long. Remember this " "password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:523 msgid "" "The `ID` line lists the login name (`unfurl`), default iteration count " "(`499`), and default seed (`to4268`). When logging in, the system will " "remember these parameters and display them, meaning that they do not have to " "be memorized. The last line lists the generated one-time password which " "corresponds to those parameters and the secret password. At the next login, " "use this one-time password." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:524 #, no-wrap msgid "Insecure Connection Initialization" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:530 msgid "" "To initialize or change the secret password on an insecure system, a secure " "connection is needed to some place where `opiekey` can be run. This might " "be a shell prompt on a trusted machine. An iteration count is needed, where " "100 is probably a good value, and the seed can either be specified or the " "randomly-generated one used. On the insecure connection, the machine being " "initialized, use man:opiepasswd[1]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:534 #, no-wrap msgid "% opiepasswd\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:543 #, no-wrap msgid "" "Updating unfurl:\n" "You need the response from an OTP generator.\n" "Old secret pass phrase:\n" "\totp-md5 498 to4268 ext\n" "\tResponse: GAME GAG WELT OUT DOWN CHAT\n" "New secret pass phrase:\n" "\totp-md5 499 to4269\n" "\tResponse: LINE PAP MILK NELL BUOY TROY\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:546 #, no-wrap msgid "" "ID mark OTP key is 499 gr4269\n" "LINE PAP MILK NELL BUOY TROY\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:550 msgid "" "To accept the default seed, press kbd:[Return]. Before entering an access " "password, move over to the secure connection and give it the same parameters:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:558 #: documentation/content/en/books/handbook/security/_index.adoc:599 #, no-wrap msgid "" "% opiekey 498 to4268\n" "Using the MD5 algorithm to compute response.\n" "Reminder: Do not use opiekey from telnet or dial-in sessions.\n" "Enter secret pass phrase:\n" "GAME GAG WELT OUT DOWN CHAT\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:561 msgid "" "Switch back over to the insecure connection, and copy the generated one-time " "password over to the relevant program." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:562 #, no-wrap msgid "Generating a Single One-time Password" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:565 msgid "" "After initializing OPIE and logging in, a prompt like this will be displayed:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:572 #, no-wrap msgid "" "% telnet example.com\n" "Trying 10.0.0.1...\n" "Connected to example.com\n" "Escape character is '^]'.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:574 #, no-wrap msgid "FreeBSD/i386 (example.com) (ttypa)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:578 #, no-wrap msgid "" "login: \n" "otp-md5 498 gr4269 ext\n" "Password:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:583 msgid "" "The OPIE prompt provides a useful feature. If kbd:[Return] is pressed at " "the password prompt, the prompt will turn echo on and display what is " "typed. This can be useful when attempting to type in a password by hand " "from a printout." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:589 msgid "" "At this point, generate the one-time password to answer this login prompt. " "This must be done on a trusted system where it is safe to run man:" "opiekey[1]. There are versions of this command for Windows(R), Mac OS(R) " "and FreeBSD. This command needs the iteration count and the seed as command " "line options. Use cut-and-paste from the login prompt on the machine being " "logged in to." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:591 msgid "On the trusted system:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:602 msgid "Once the one-time password is generated, continue to log in." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:603 #, no-wrap msgid "Generating Multiple One-time Passwords" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:607 msgid "" "Sometimes there is no access to a trusted machine or secure connection. In " "this case, it is possible to use man:opiekey[1] to generate a number of one-" "time passwords beforehand. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:619 #, no-wrap msgid "" "% opiekey -n 5 30 zz99999\n" "Using the MD5 algorithm to compute response.\n" "Reminder: Do not use opiekey from telnet or dial-in sessions.\n" "Enter secret pass phrase: \n" "26: JOAN BORE FOSS DES NAY QUIT\n" "27: LATE BIAS SLAY FOLK MUCH TRIG\n" "28: SALT TIN ANTI LOON NEAL USE\n" "29: RIO ODIN GO BYE FURY TIC\n" "30: GREW JIVE SAN GIRD BOIL PHI\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:626 msgid "" "The `-n 5` requests five keys in sequence, and `30` specifies what the last " "iteration number should be. Note that these are printed out in _reverse_ " "order of use. The really paranoid might want to write the results down by " "hand; otherwise, print the list. Each line shows both the iteration count " "and the one-time password. Scratch off the passwords as they are used." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:627 #, no-wrap msgid "Restricting Use of UNIX(R) Passwords" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:632 msgid "" "OPIE can restrict the use of UNIX(R) passwords based on the IP address of a " "login session. The relevant file is [.filename]#/etc/opieaccess#, which is " "present by default. Refer to man:opieaccess[5] for more information on this " "file and which security considerations to be aware of when using it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:634 msgid "Here is a sample [.filename]#opieaccess#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:638 #, no-wrap msgid "permit 192.168.0.0 255.255.0.0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:641 msgid "" "This line allows users whose IP source address (which is vulnerable to " "spoofing) matches the specified value and mask, to use UNIX(R) passwords at " "any time." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:643 msgid "" "If no rules in [.filename]#opieaccess# are matched, the default is to deny " "non-OPIE logins." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:645 #, no-wrap msgid "TCP Wrapper" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:650 msgid "" "TCP Wrapper is a host-based access control system which extends the " "abilities of crossref:network-servers[network-inetd,“The inetd Super-" "Server”]. It can be configured to provide logging support, return messages, " "and connection restrictions for the server daemons under the control of " "inetd. Refer to man:tcpd[8] for more information about TCP Wrapper and its " "features." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:653 msgid "" "TCP Wrapper should not be considered a replacement for a properly configured " "firewall. Instead, TCP Wrapper should be used in conjunction with a " "firewall and other security enhancements in order to provide another layer " "of protection in the implementation of a security policy." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:654 #, no-wrap msgid "Initial Configuration" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:657 msgid "" "To enable TCP Wrapper in FreeBSD, add the following lines to [.filename]#/" "etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:662 #, no-wrap msgid "" "inetd_enable=\"YES\"\n" "inetd_flags=\"-Ww\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:665 msgid "Then, properly configure [.filename]#/etc/hosts.allow#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:670 msgid "" "Unlike other implementations of TCP Wrapper, the use of [.filename]#hosts." "deny# is deprecated in FreeBSD. All configuration options should be placed " "in [.filename]#/etc/hosts.allow#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:674 msgid "" "In the simplest configuration, daemon connection policies are set to either " "permit or block, depending on the options in [.filename]#/etc/hosts.allow#. " "The default configuration in FreeBSD is to allow all connections to the " "daemons started with inetd." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:678 msgid "" "Basic configuration usually takes the form of `daemon : address : action`, " "where `daemon` is the daemon which inetd started, `address` is a valid " "hostname, IP address, or an IPv6 address enclosed in brackets ([ ]), and " "`action` is either `allow` or `deny`. TCP Wrapper uses a first rule match " "semantic, meaning that the configuration file is scanned from the beginning " "for a matching rule. When a match is found, the rule is applied and the " "search process stops." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:680 msgid "" "For example, to allow POP3 connections via the package:mail/qpopper[] " "daemon, the following lines should be appended to [.filename]#hosts.allow#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:685 #, no-wrap msgid "" "# This line is required for POP3 connections:\n" "qpopper : ALL : allow\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:688 msgid "Whenever this file is edited, restart inetd:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:692 #, no-wrap msgid "# service inetd restart\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:694 #, no-wrap msgid "Advanced Configuration" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:701 msgid "" "TCP Wrapper provides advanced options to allow more control over the way " "connections are handled. In some cases, it may be appropriate to return a " "comment to certain hosts or daemon connections. In other cases, a log entry " "should be recorded or an email sent to the administrator. Other situations " "may require the use of a service for local connections only. This is all " "possible through the use of configuration options known as wildcards, " "expansion characters, and external command execution." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:706 msgid "" "Suppose that a situation occurs where a connection should be denied yet a " "reason should be sent to the host who attempted to establish that " "connection. That action is possible with `twist`. When a connection " "attempt is made, `twist` executes a shell command or script. An example " "exists in [.filename]#hosts.allow#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:713 #, no-wrap msgid "" "# The rest of the daemons are protected.\n" "ALL : ALL \\\n" "\t: severity auth.info \\\n" "\t: twist /bin/echo \"You are not welcome to use %d from %h.\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:719 msgid "" "In this example, the message \"You are not allowed to use _daemon name_ from " "_hostname_.\" will be returned for any daemon not configured in [." "filename]#hosts.allow#. This is useful for sending a reply back to the " "connection initiator right after the established connection is dropped. Any " "message returned _must_ be wrapped in quote (`\"`) characters." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:723 msgid "" "It may be possible to launch a denial of service attack on the server if an " "attacker floods these daemons with connection requests." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:729 msgid "" "Another possibility is to use `spawn`. Like `twist`, `spawn` implicitly " "denies the connection and may be used to run external shell commands or " "scripts. Unlike `twist`, `spawn` will not send a reply back to the host who " "established the connection. For example, consider the following " "configuration:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:737 #, no-wrap msgid "" "# We do not allow connections from example.com:\n" "ALL : .example.com \\\n" "\t: spawn (/bin/echo %a from %h attempted to access %d >> \\\n" "\t /var/log/connections.log) \\\n" "\t: deny\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:742 msgid "" "This will deny all connection attempts from `*.example.com` and log the " "hostname, IP address, and the daemon to which access was attempted to [." "filename]#/var/log/connections.log#. This example uses the substitution " "characters `%a` and `%h`. Refer to man:hosts_access[5] for the complete " "list." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:746 msgid "" "To match every instance of a daemon, domain, or IP address, use `ALL`. " "Another wildcard is `PARANOID` which may be used to match any host which " "provides an IP address that may be forged because the IP address differs " "from its resolved hostname. In this example, all connection requests to " "Sendmail which have an IP address that varies from its hostname will be " "denied:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:751 #, no-wrap msgid "" "# Block possibly spoofed requests to sendmail:\n" "sendmail : PARANOID : deny\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:756 msgid "" "Using the `PARANOID` wildcard will result in denied connections if the " "client or server has a broken DNS setup." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:759 msgid "" "To learn more about wildcards and their associated functionality, refer to " "man:hosts_access[5]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:763 msgid "" "When adding new configuration lines, make sure that any unneeded entries for " "that daemon are commented out in [.filename]#hosts.allow#." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:766 #, no-wrap msgid "Kerberos" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:772 msgid "" "Kerberos is a network authentication protocol which was originally created " "by the Massachusetts Institute of Technology (MIT) as a way to securely " "provide authentication across a potentially hostile network. The Kerberos " "protocol uses strong cryptography so that both a client and server can prove " "their identity without sending any unencrypted secrets over the network. " "Kerberos can be described as an identity-verifying proxy system and as a " "trusted third-party authentication system. After a user authenticates with " "Kerberos, their communications can be encrypted to assure privacy and data " "integrity." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:776 msgid "" "The only function of Kerberos is to provide the secure authentication of " "users and servers on the network. It does not provide authorization or " "auditing functions. It is recommended that Kerberos be used with other " "security methods which provide authorization and audit services." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:784 msgid "" "The current version of the protocol is version 5, described in RFC 4120. " "Several free implementations of this protocol are available, covering a wide " "range of operating systems. MIT continues to develop their Kerberos " "package. It is commonly used in the US as a cryptography product, and has " "historically been subject to US export regulations. In FreeBSD, MITKerberos " "is available as the package:security/krb5[] package or port. The Heimdal " "Kerberos implementation was explicitly developed outside of the US to avoid " "export regulations. The Heimdal Kerberos distribution is included in the " "base FreeBSD installation, and another distribution with more configurable " "options is available as package:security/heimdal[] in the Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:787 msgid "" "In Kerberos users and services are identified as \"principals\" which are " "contained within an administrative grouping, called a \"realm\". A typical " "user principal would be of the form `_user_@_REALM_` (realms are " "traditionally uppercase)." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:789 msgid "" "This section provides a guide on how to set up Kerberos using the Heimdal " "distribution included in FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:791 msgid "" "For purposes of demonstrating a Kerberos installation, the name spaces will " "be as follows:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:793 msgid "The DNS domain (zone) will be `example.org`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:794 msgid "The Kerberos realm will be `EXAMPLE.ORG`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:799 msgid "" "Use real domain names when setting up Kerberos, even if it will run " "internally. This avoids DNS problems and assures inter-operation with other " "Kerberos realms." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:801 #, no-wrap msgid "Setting up a Heimdal KDC" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:807 msgid "" "The Key Distribution Center (KDC) is the centralized authentication service " "that Kerberos provides, the \"trusted third party\" of the system. It is " "the computer that issues Kerberos tickets, which are used for clients to " "authenticate to servers. As the KDC is considered trusted by all other " "computers in the Kerberos realm, it has heightened security concerns. " "Direct access to the KDC should be limited." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:809 msgid "" "While running a KDC requires few computing resources, a dedicated machine " "acting only as a KDC is recommended for security reasons." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:811 msgid "To begin, install the package:security/heimdal[] package as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:815 #, no-wrap msgid "# pkg install heimdal\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:818 msgid "Next, update [.filename]#/etc/rc.conf# using `sysrc` as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:823 #, no-wrap msgid "" "# sysrc kdc_enable=yes\n" "# sysrc kadmind_enable=yes\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:826 msgid "Next, edit [.filename]#/etc/krb5.conf# as follows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:838 #, no-wrap msgid "" "[libdefaults]\n" " default_realm = EXAMPLE.ORG\n" "[realms]\n" " EXAMPLE.ORG = {\n" "\tkdc = kerberos.example.org\n" "\tadmin_server = kerberos.example.org\n" " }\n" "[domain_realm]\n" " .example.org = EXAMPLE.ORG\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:842 msgid "" "In this example, the KDC will use the fully-qualified hostname `kerberos." "example.org`. The hostname of the KDC must be resolvable in the DNS." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:845 msgid "" "Kerberos can also use the DNS to locate KDCs, instead of a `[realms]` " "section in [.filename]#/etc/krb5.conf#. For large organizations that have " "their own DNS servers, the above example could be trimmed to:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:852 #, no-wrap msgid "" "[libdefaults]\n" " default_realm = EXAMPLE.ORG\n" "[domain_realm]\n" " .example.org = EXAMPLE.ORG\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:855 msgid "With the following lines being included in the `example.org` zone file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:863 #, no-wrap msgid "" "_kerberos._udp IN SRV 01 00 88 kerberos.example.org.\n" "_kerberos._tcp IN SRV 01 00 88 kerberos.example.org.\n" "_kpasswd._udp IN SRV 01 00 464 kerberos.example.org.\n" "_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org.\n" "_kerberos IN TXT EXAMPLE.ORG\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:868 msgid "" "In order for clients to be able to find the Kerberos services, they _must_ " "have either a fully configured [.filename]#/etc/krb5.conf# or a minimally " "configured [.filename]#/etc/krb5.conf# _and_ a properly configured DNS " "server." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:874 msgid "" "Next, create the Kerberos database which contains the keys of all principals " "(users and hosts) encrypted with a master password. It is not required to " "remember this password as it will be stored in [.filename]#/var/heimdal/m-" "key#; it would be reasonable to use a 45-character random password for this " "purpose. To create the master key, run `kstash` and enter a password:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:880 #, no-wrap msgid "" "# kstash\n" "Master key: xxxxxxxxxxxxxxxxxxxxxxx\n" "Verifying password - Master key: xxxxxxxxxxxxxxxxxxxxxxx\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:886 msgid "" "Once the master key has been created, the database should be initialized. " "The Kerberos administrative tool man:kadmin[8] can be used on the KDC in a " "mode that operates directly on the database, without using the man:" "kadmind[8] network service, as `kadmin -l`. This resolves the chicken-and-" "egg problem of trying to connect to the database before it is created. At " "the `kadmin` prompt, use `init` to create the realm's initial database:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:892 #, no-wrap msgid "" "# kadmin -l\n" "kadmin> init EXAMPLE.ORG\n" "Realm max ticket life [unlimited]:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:897 msgid "" "Lastly, while still in `kadmin`, create the first principal using `add`. " "Stick to the default options for the principal for now, as these can be " "changed later with `modify`. Type `?` at the prompt to see the available " "options." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:908 #, no-wrap msgid "" "kadmin> add tillman\n" "Max ticket life [unlimited]:\n" "Max renewable life [unlimited]:\n" "Principal expiration time [never]:\n" "Password expiration time [never]:\n" "Attributes []:\n" "Password: xxxxxxxx\n" "Verifying password - Password: xxxxxxxx\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:911 msgid "Next, start the KDC services by running:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:916 #, no-wrap msgid "" "# service kdc start\n" "# service kadmind start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:919 msgid "" "While there will not be any kerberized daemons running at this point, it is " "possible to confirm that the KDC is functioning by obtaining a ticket for " "the principal that was just created:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:924 #, no-wrap msgid "" "% kinit tillman\n" "tillman@EXAMPLE.ORG's Password:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:927 msgid "Confirm that a ticket was successfully obtained using `klist`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:933 #, no-wrap msgid "" "% klist\n" "Credentials cache: FILE:/tmp/krb5cc_1001\n" "\tPrincipal: tillman@EXAMPLE.ORG\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:936 #, no-wrap msgid "" " Issued Expires Principal\n" "Aug 27 15:37:58 2013 Aug 28 01:37:58 2013 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:939 msgid "The temporary ticket can be destroyed when the test is finished:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:943 #, no-wrap msgid "% kdestroy\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:945 #, no-wrap msgid "Configuring a Server to Use Kerberos" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:949 msgid "" "The first step in configuring a server to use Kerberos authentication is to " "ensure that it has the correct configuration in [.filename]#/etc/krb5." "conf#. The version from the KDC can be used as-is, or it can be regenerated " "on the new system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:958 msgid "" "Next, create [.filename]#/etc/krb5.keytab# on the server. This is the main " "part of \"Kerberizing\" a service - it corresponds to generating a secret " "shared between the service and the KDC. The secret is a cryptographic key, " "stored in a \"keytab\". The keytab contains the server's host key, which " "allows it and the KDC to verify each others' identity. It must be " "transmitted to the server in a secure fashion, as the security of the server " "can be broken if the key is made public. Typically, the [.filename]#keytab# " "is generated on an administrator's trusted machine using `kadmin`, then " "securely transferred to the server, e.g., with man:scp[1]; it can also be " "created directly on the server if that is consistent with the desired " "security policy. It is very important that the keytab is transmitted to the " "server in a secure fashion: if the key is known by some other party, that " "party can impersonate any user to the server! Using `kadmin` on the server " "directly is convenient, because the entry for the host principal in the KDC " "database is also created using `kadmin`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:962 msgid "" "Of course, `kadmin` is a kerberized service; a Kerberos ticket is needed to " "authenticate to the network service, but to ensure that the user running " "`kadmin` is actually present (and their session has not been hijacked), " "`kadmin` will prompt for the password to get a fresh ticket. The principal " "authenticating to the kadmin service must be permitted to use the `kadmin` " "interface, as specified in [.filename]#/var/heimdal/kadmind.acl#. See the " "section titled \"Remote administration\" in `info heimdal` for details on " "designing access control lists. Instead of enabling remote `kadmin` access, " "the administrator could securely connect to the KDC via the local console or " "man:ssh[1], and perform administration locally using `kadmin -l`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:966 msgid "" "After installing [.filename]#/etc/krb5.conf#, use `add --random-key` in " "`kadmin`. This adds the server's host principal to the database, but does " "not extract a copy of the host principal key to a keytab. To generate the " "keytab, use `ext` to extract the server's host principal key to its own " "keytab:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:978 #, no-wrap msgid "" "# kadmin\n" "kadmin> add --random-key host/myserver.example.org\n" "Max ticket life [unlimited]:\n" "Max renewable life [unlimited]:\n" "Principal expiration time [never]:\n" "Password expiration time [never]:\n" "Attributes []:\n" "kadmin> ext_keytab host/myserver.example.org\n" "kadmin> exit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:982 msgid "" "Note that `ext_keytab` stores the extracted key in [.filename]#/etc/krb5." "keytab# by default. This is good when being run on the server being " "kerberized, but the `--keytab _path/to/file_` argument should be used when " "the keytab is being extracted elsewhere:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:988 #, no-wrap msgid "" "# kadmin\n" "kadmin> ext_keytab --keytab=/tmp/example.keytab host/myserver.example.org\n" "kadmin> exit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:992 msgid "" "The keytab can then be securely copied to the server using man:scp[1] or a " "removable media. Be sure to specify a non-default keytab name to avoid " "inserting unneeded keys into the system's keytab." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:997 msgid "" "At this point, the server can read encrypted messages from the KDC using its " "shared key, stored in [.filename]#krb5.keytab#. It is now ready for the " "Kerberos-using services to be enabled. One of the most common such services " "is man:sshd[8], which supports Kerberos via the GSS-API. In [.filename]#/" "etc/ssh/sshd_config#, add the line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1001 #, no-wrap msgid "GSSAPIAuthentication yes\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1004 msgid "" "After making this change, man:sshd[8] must be restarted for the new " "configuration to take effect: `service sshd restart`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1005 #, no-wrap msgid "Configuring a Client to Use Kerberos" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1009 msgid "" "As it was for the server, the client requires configuration in [.filename]#/" "etc/krb5.conf#. Copy the file in place (securely) or re-enter it as needed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1014 msgid "" "Test the client by using `kinit`, `klist`, and `kdestroy` from the client to " "obtain, show, and then delete a ticket for an existing principal. Kerberos " "applications should also be able to connect to Kerberos enabled servers. If " "that does not work but obtaining a ticket does, the problem is likely with " "the server and not with the client or the KDC. In the case of kerberized " "man:ssh[1], GSS-API is disabled by default, so test using `ssh -o " "GSSAPIAuthentication=yes _hostname_`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1016 msgid "" "When testing a Kerberized application, try using a packet sniffer such as " "`tcpdump` to confirm that no sensitive information is sent in the clear." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1019 msgid "" "Various Kerberos client applications are available. With the advent of a " "bridge so that applications using SASL for authentication can use GSS-API " "mechanisms as well, large classes of client applications can use Kerberos " "for authentication, from Jabber clients to IMAP clients." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1024 msgid "" "Users within a realm typically have their Kerberos principal mapped to a " "local user account. Occasionally, one needs to grant access to a local user " "account to someone who does not have a matching Kerberos principal. For " "example, `tillman@EXAMPLE.ORG` may need access to the local user account " "`webdevelopers`. Other principals may also need access to that local " "account." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1027 msgid "" "The [.filename]#.k5login# and [.filename]#.k5users# files, placed in a " "user's home directory, can be used to solve this problem. For example, if " "the following [.filename]#.k5login# is placed in the home directory of " "`webdevelopers`, both principals listed will have access to that account " "without requiring a shared password:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1032 #, no-wrap msgid "" "tillman@example.org\n" "jdoe@example.org\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1035 msgid "Refer to man:ksu[1] for more information about [.filename]#.k5users#." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1036 #, no-wrap msgid "MIT Differences" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1040 msgid "" "The major difference between the MIT and Heimdal implementations is that " "`kadmin` has a different, but equivalent, set of commands and uses a " "different protocol. If the KDC is MIT, the Heimdal version of `kadmin` " "cannot be used to administer the KDC remotely, and vice versa." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1044 msgid "" "Client applications may also use slightly different command line options to " "accomplish the same tasks. Following the instructions at http://web.mit.edu/" "Kerberos/www/[http://web.mit.edu/Kerberos/www/] is recommended. Be careful " "of path issues: the MIT port installs into [.filename]#/usr/local/# by " "default, and the FreeBSD system applications run instead of the MIT versions " "if `PATH` lists the system directories first." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1046 msgid "" "When using MIT Kerberos as a KDC on FreeBSD, the following edits should also " "be made to [.filename]#rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1054 #, no-wrap msgid "" "kdc_program=\"/usr/local/sbin/kdc\"\n" "kadmind_program=\"/usr/local/sbin/kadmind\"\n" "kdc_flags=\"\"\n" "kdc_enable=\"YES\"\n" "kadmind_enable=\"YES\"\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1056 #, no-wrap msgid "Kerberos Tips, Tricks, and Troubleshooting" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1059 msgid "" "When configuring and troubleshooting Kerberos, keep the following points in " "mind:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1061 msgid "" "When using either Heimdal or MITKerberos from ports, ensure that the `PATH` " "lists the port's versions of the client applications before the system " "versions." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1062 msgid "" "If all the computers in the realm do not have synchronized time settings, " "authentication may fail. crossref:network-servers[network-ntp,“Clock " "Synchronization with NTP”] describes how to synchronize clocks using NTP." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1063 msgid "" "If the hostname is changed, the `host/` principal must be changed and the " "keytab updated. This also applies to special keytab entries like the `HTTP/` " "principal used for Apache's package:www/mod_auth_kerb[]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1064 msgid "" "All hosts in the realm must be both forward and reverse resolvable in DNS " "or, at a minimum, exist in [.filename]#/etc/hosts#. CNAMEs will work, but " "the A and PTR records must be correct and in place. The error message for " "unresolvable hosts is not intuitive: `Kerberos5 refuses authentication " "because Read req failed: Key table entry not found`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1065 msgid "" "Some operating systems that act as clients to the KDC do not set the " "permissions for `ksu` to be setuid `root`. This means that `ksu` does not " "work. This is a permissions problem, not a KDC error." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1066 msgid "" "With MITKerberos, to allow a principal to have a ticket life longer than the " "default lifetime of ten hours, use `modify_principal` at the man:kadmin[8] " "prompt to change the `maxlife` of both the principal in question and the " "`krbtgt` principal. The principal can then use `kinit -l` to request a " "ticket with a longer lifetime." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1067 msgid "" "When running a packet sniffer on the KDC to aid in troubleshooting while " "running `kinit` from a workstation, the Ticket Granting Ticket (TGT) is sent " "immediately, even before the password is typed. This is because the Kerberos " "server freely transmits a TGT to any unauthorized request. However, every " "TGT is encrypted in a key derived from the user's password. When a user " "types their password, it is not sent to the KDC, it is instead used to " "decrypt the TGT that `kinit` already obtained. If the decryption process " "results in a valid ticket with a valid time stamp, the user has valid " "Kerberos credentials. These credentials include a session key for " "establishing secure communications with the Kerberos server in the future, " "as well as the actual TGT, which is encrypted with the Kerberos server's own " "key. This second layer of encryption allows the Kerberos server to verify " "the authenticity of each TGT." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1068 msgid "" "Host principals can have a longer ticket lifetime. If the user principal has " "a lifetime of a week but the host being connected to has a lifetime of nine " "hours, the user cache will have an expired host principal and the ticket " "cache will not work as expected." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1069 msgid "" "When setting up [.filename]#krb5.dict# to prevent specific bad passwords " "from being used as described in man:kadmind[8], remember that it only " "applies to principals that have a password policy assigned to them. The " "format used in [.filename]#krb5.dict# is one string per line. Creating a " "symbolic link to [.filename]#/usr/share/dict/words# might be useful." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1070 #, no-wrap msgid "Mitigating Kerberos Limitations" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1075 msgid "" "Since Kerberos is an all or nothing approach, every service enabled on the " "network must either be modified to work with Kerberos or be otherwise " "secured against network attacks. This is to prevent user credentials from " "being stolen and re-used. An example is when Kerberos is enabled on all " "remote shells but the non-Kerberized POP3 mail server sends passwords in " "plain text." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1080 msgid "" "The KDC is a single point of failure. By design, the KDC must be as secure " "as its master password database. The KDC should have absolutely no other " "services running on it and should be physically secure. The danger is high " "because Kerberos stores all passwords encrypted with the same master key " "which is stored as a file on the KDC." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1084 msgid "" "A compromised master key is not quite as bad as one might fear. The master " "key is only used to encrypt the Kerberos database and as a seed for the " "random number generator. As long as access to the KDC is secure, an " "attacker cannot do much with the master key." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1087 msgid "" "If the KDC is unavailable, network services are unusable as authentication " "cannot be performed. This can be alleviated with a single master KDC and " "one or more slaves, and with careful implementation of secondary or fall-" "back authentication using PAM." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1092 msgid "" "Kerberos allows users, hosts and services to authenticate between " "themselves. It does not have a mechanism to authenticate the KDC to the " "users, hosts, or services. This means that a trojaned `kinit` could record " "all user names and passwords. File system integrity checking tools like " "package:security/tripwire[] can alleviate this." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1093 #, no-wrap msgid "Resources and Further Information" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1096 msgid "" "http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html[The Kerberos FAQ]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1097 msgid "" "http://web.mit.edu/Kerberos/www/dialogue.html[Designing an Authentication " "System: a Dialog in Four Scenes]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1098 msgid "" "https://www.ietf.org/rfc/rfc4120.txt[RFC 4120, The Kerberos Network " "Authentication Service (V5)]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1099 msgid "http://web.mit.edu/Kerberos/www/[MIT Kerberos home page]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1100 msgid "" "https://github.com/heimdal/heimdal/wiki[Heimdal Kerberos project wiki page]" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:1102 #, no-wrap msgid "OpenSSL" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1106 msgid "" "OpenSSL is an open source implementation of the SSL and TLS protocols. It " "provides an encryption transport layer on top of the normal communications " "layer, allowing it to be intertwined with many network applications and " "services." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1108 msgid "" "The version of OpenSSL included in FreeBSD supports Transport Layer Security " "1.0/1.1/1.2/1.3 (TLSv1/TLSv1.1/TLSv1.2/TLSv1.3) network security protocols " "and can be used as a general cryptographic library." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1113 msgid "" "OpenSSL is often used to encrypt authentication of mail clients and to " "secure web based transactions such as credit card payments. Some ports, " "such as package:www/apache24[] and package:databases/postgresql11-server[], " "include a compile option for building with OpenSSL. If selected, the port " "will add support using OpenSSL from the base system. To instead have the " "port compile against OpenSSL from the package:security/openssl[] port, add " "the following to [.filename]#/etc/make.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1117 #, no-wrap msgid "DEFAULT_VERSIONS+= ssl=openssl\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1125 msgid "" "Another common use of OpenSSL is to provide certificates for use with " "software applications. Certificates can be used to verify the credentials " "of a company or individual. If a certificate has not been signed by an " "external _Certificate Authority_ (CA), such as http://www.verisign." "com[http://www.verisign.com], the application that uses the certificate will " "produce a warning. There is a cost associated with obtaining a signed " "certificate and using a signed certificate is not mandatory as certificates " "can be self-signed. However, using an external authority will prevent " "warnings and can put users at ease." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1128 msgid "" "This section demonstrates how to create and use certificates on a FreeBSD " "system. Refer to crossref:network-servers[ldap-config,“Configuring an LDAP " "Server”] for an example of how to create a CA for signing one's own " "certificates." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1130 msgid "" "For more information about SSL, read the free https://www.feistyduck.com/" "books/openssl-cookbook/[OpenSSL Cookbook]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1131 #, no-wrap msgid "Generating Certificates" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1137 msgid "" "To generate a certificate that will be signed by an external CA, issue the " "following command and input the information requested at the prompts. This " "input information will be written to the certificate. At the `Common Name` " "prompt, input the fully qualified name for the system that will use the " "certificate. If this name does not match the server, the application " "verifying the certificate will issue a warning to the user, rendering the " "verification provided by the certificate as useless." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1160 #, no-wrap msgid "" "# openssl req -new -nodes -out req.pem -keyout cert.key -sha256 -newkey rsa:2048\n" "Generating a 2048 bit RSA private key\n" "..................+++\n" ".............................................................+++\n" "writing new private key to 'cert.key'\n" "-----\n" "You are about to be asked to enter information that will be incorporated\n" "into your certificate request.\n" "What you are about to enter is what is called a Distinguished Name or a DN.\n" "There are quite a few fields but you can leave some blank\n" "For some fields there will be a default value,\n" "If you enter '.', the field will be left blank.\n" "-----\n" "Country Name (2 letter code) [AU]:US\n" "State or Province Name (full name) [Some-State]:PA\n" "Locality Name (e.g., city) []:Pittsburgh\n" "Organization Name (e.g., company) [Internet Widgits Pty Ltd]:My Company\n" "Organizational Unit Name (e.g., section) []:Systems Administrator\n" "Common Name (e.g., YOUR name) []:localhost.example.org\n" "Email Address []:trhodes@FreeBSD.org\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1165 #, no-wrap msgid "" "Please enter the following 'extra' attributes\n" "to be sent with your certificate request\n" "A challenge password []:\n" "An optional company name []:Another Name\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1169 msgid "" "Other options, such as the expire time and alternate encryption algorithms, " "are available when creating a certificate. A complete list of options is " "described in man:openssl[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1174 msgid "" "This command will create two files in the current directory. The " "certificate request, [.filename]#req.pem#, can be sent to a CA who will " "validate the entered credentials, sign the request, and return the signed " "certificate. The second file, [.filename]#cert.key#, is the private key for " "the certificate and should be stored in a secure location. If this falls in " "the hands of others, it can be used to impersonate the user or the server." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1177 msgid "" "Alternately, if a signature from a CA is not required, a self-signed " "certificate can be created. First, generate the RSA key:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1186 #, no-wrap msgid "" "# openssl genrsa -rand -genkey -out cert.key 2048\n" "0 semi-random bytes loaded\n" "Generating RSA private key, 2048 bit long modulus\n" ".............................................+++\n" ".................................................................................................................+++\n" "e is 65537 (0x10001)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1189 msgid "" "Use this key to create a self-signed certificate. Follow the usual prompts " "for creating a certificate:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1207 #, no-wrap msgid "" "# openssl req -new -x509 -days 365 -key cert.key -out cert.crt -sha256\n" "You are about to be asked to enter information that will be incorporated\n" "into your certificate request.\n" "What you are about to enter is what is called a Distinguished Name or a DN.\n" "There are quite a few fields but you can leave some blank\n" "For some fields there will be a default value,\n" "If you enter '.', the field will be left blank.\n" "-----\n" "Country Name (2 letter code) [AU]:US\n" "State or Province Name (full name) [Some-State]:PA\n" "Locality Name (e.g., city) []:Pittsburgh\n" "Organization Name (e.g., company) [Internet Widgits Pty Ltd]:My Company\n" "Organizational Unit Name (e.g., section) []:Systems Administrator\n" "Common Name (e.g. server FQDN or YOUR name) []:localhost.example.org\n" "Email Address []:trhodes@FreeBSD.org\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1212 msgid "" "This will create two new files in the current directory: a private key file " "[.filename]#cert.key#, and the certificate itself, [.filename]#cert.crt#. " "These should be placed in a directory, preferably under [.filename]#/etc/ssl/" "#, which is readable only by `root`. Permissions of `0700` are appropriate " "for these files and can be set using `chmod`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1213 #, no-wrap msgid "Using Certificates" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1216 msgid "" "One use for a certificate is to encrypt connections to the Sendmail mail " "server in order to prevent the use of clear text authentication." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1221 msgid "" "Some mail clients will display an error if the user has not installed a " "local copy of the certificate. Refer to the documentation included with the " "software for more information on certificate installation." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1225 msgid "" "In FreeBSD 10.0-RELEASE and above, it is possible to create a self-signed " "certificate for Sendmail automatically. To enable this, add the following " "lines to [.filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1231 #, no-wrap msgid "" "sendmail_enable=\"YES\"\n" "sendmail_cert_create=\"YES\"\n" "sendmail_cert_cn=\"localhost.example.org\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1236 msgid "" "This will automatically create a self-signed certificate, [.filename]#/etc/" "mail/certs/host.cert#, a signing key, [.filename]#/etc/mail/certs/host.key#, " "and a CA certificate, [.filename]#/etc/mail/certs/cacert.pem#. The " "certificate will use the `Common Name` specified in `sendmail_cert_cn`. " "After saving the edits, restart Sendmail:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1240 #, no-wrap msgid "# service sendmail restart\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1244 msgid "" "If all went well, there will be no error messages in [.filename]#/var/log/" "maillog#. For a simple test, connect to the mail server's listening port " "using `telnet`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1267 #, no-wrap msgid "" "# telnet example.com 25\n" "Trying 192.0.34.166...\n" "Connected to example.com.\n" "Escape character is '^]'.\n" "220 example.com ESMTP Sendmail 8.14.7/8.14.7; Fri, 18 Apr 2014 11:50:32 -0400 (EDT)\n" "ehlo example.com\n" "250-example.com Hello example.com [192.0.34.166], pleased to meet you\n" "250-ENHANCEDSTATUSCODES\n" "250-PIPELINING\n" "250-8BITMIME\n" "250-SIZE\n" "250-DSN\n" "250-ETRN\n" "250-AUTH LOGIN PLAIN\n" "250-STARTTLS\n" "250-DELIVERBY\n" "250 HELP\n" "quit\n" "221 2.0.0 example.com closing connection\n" "Connection closed by foreign host.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1270 msgid "" "If the `STARTTLS` line appears in the output, everything is working " "correctly." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:1272 #, no-wrap msgid "VPN over IPsec" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1277 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/books/handbook/security/_index.adoc:1279 msgid "IPsec is comprised of the following sub-protocols:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1281 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/books/handbook/security/_index.adoc:1282 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/books/handbook/security/_index.adoc:1283 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/books/handbook/security/_index.adoc:1285 msgid "" "These protocols can either be used together or separately, depending on the " "environment." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1290 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/books/handbook/security/_index.adoc:1293 msgid "" "IPsec support is enabled by default on FreeBSD 11 and later. For previous " "versions of FreeBSD, add these options to a custom kernel configuration file " "and rebuild the kernel using the instructions in crossref:" "kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1298 #, no-wrap msgid "" "options IPSEC IP security\n" "device crypto\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1301 msgid "" "If IPsec debugging support is desired, the following kernel option should " "also be added:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1305 #, no-wrap msgid "options IPSEC_DEBUG debug for IP security\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1309 msgid "" "This rest of this chapter demonstrates the process of setting up an IPsecVPN " "between a home network and a corporate network. In the example scenario:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1311 msgid "" "Both sites are connected to the Internet through a gateway that is running " "FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1312 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/books/handbook/security/_index.adoc:1313 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/books/handbook/security/_index.adoc:1318 #, 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/books/handbook/security/_index.adoc:1320 #, no-wrap msgid "Configuring a VPN on FreeBSD" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1324 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/books/handbook/security/_index.adoc:1327 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/books/handbook/security/_index.adoc:1333 #, 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/books/handbook/security/_index.adoc:1340 #, 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/books/handbook/security/_index.adoc:1344 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/books/handbook/security/_index.adoc:1351 #, 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/books/handbook/security/_index.adoc:1354 msgid "Here is the output from the corporate gateway:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1361 #, 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/books/handbook/security/_index.adoc:1364 msgid "" "Once complete, both internal IP addresses should be reachable using man:" "ping[8]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1376 #, 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/books/handbook/security/_index.adoc:1387 #, 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/books/handbook/security/_index.adoc:1392 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/books/handbook/security/_index.adoc:1399 #, 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/books/handbook/security/_index.adoc:1403 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/books/handbook/security/_index.adoc:1414 #, 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/books/handbook/security/_index.adoc:1423 #, 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/books/handbook/security/_index.adoc:1428 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/books/handbook/security/_index.adoc:1433 #, 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/books/handbook/security/_index.adoc:1441 #, 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/books/handbook/security/_index.adoc:1451 #, 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/books/handbook/security/_index.adoc:1457 #, 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/books/handbook/security/_index.adoc:1470 #, 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/books/handbook/security/_index.adoc:1479 #, 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/books/handbook/security/_index.adoc:1488 #, 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/books/handbook/security/_index.adoc:1491 msgid "" "For descriptions of each available option, refer to the manual page for [." "filename]#racoon.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1493 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/books/handbook/security/_index.adoc:1496 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/books/handbook/security/_index.adoc:1504 #, 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/books/handbook/security/_index.adoc:1507 msgid "" "Once in place, racoon may be started on both gateways using the following " "command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1511 #, 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/books/handbook/security/_index.adoc:1514 msgid "The output should be similar to the following:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1529 #, 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/books/handbook/security/_index.adoc:1533 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/books/handbook/security/_index.adoc:1537 #, 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/books/handbook/security/_index.adoc:1541 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/books/handbook/security/_index.adoc:1547 #, 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/books/handbook/security/_index.adoc:1553 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/books/handbook/security/_index.adoc:1560 #, 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/books/handbook/security/_index.adoc:1565 msgid "" "The rule numbers may need to be altered depending on the current host " "configuration." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1568 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/books/handbook/security/_index.adoc:1581 #, 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/books/handbook/security/_index.adoc:1584 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/books/handbook/security/_index.adoc:1591 #, 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 "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:1594 #, no-wrap msgid "OpenSSH" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1599 msgid "" "OpenSSH is a set of network connectivity tools used to provide secure access " "to remote machines. Additionally, TCP/IP connections can be tunneled or " "forwarded securely through SSH connections. OpenSSH encrypts all traffic to " "effectively eliminate eavesdropping, connection hijacking, and other network-" "level attacks." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1601 msgid "" "OpenSSH is maintained by the OpenBSD project and is installed by default in " "FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1605 msgid "" "When data is sent over the network in an unencrypted form, network sniffers " "anywhere in between the client and server can steal user/password " "information or data transferred during the session. OpenSSH offers a " "variety of authentication and encryption methods to prevent this from " "happening. More information about OpenSSH is available from http://www." "openssh.com/[http://www.openssh.com/]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1609 msgid "" "This section provides an overview of the built-in client utilities to " "securely access other systems and securely transfer files from a FreeBSD " "system. It then describes how to configure a SSH server on a FreeBSD " "system. More information is available in the man pages mentioned in this " "chapter." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1610 #, no-wrap msgid "Using the SSH Client Utilities" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1614 msgid "" "To log into a SSH server, use `ssh` and specify a username that exists on " "that server and the IP address or hostname of the server. If this is the " "first time a connection has been made to the specified server, the user will " "be prompted to first verify the server's fingerprint:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1623 #, no-wrap msgid "" "# ssh user@example.com\n" "The authenticity of host 'example.com (10.0.0.1)' can't be established.\n" "ECDSA key fingerprint is 25:cc:73:b5:b3:96:75:3d:56:19:49:d2:5c:1f:91:3b.\n" "Are you sure you want to continue connecting (yes/no)? yes\n" "Permanently added 'example.com' (ECDSA) to the list of known hosts.\n" "Password for user@example.com: user_password\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1629 msgid "" "SSH utilizes a key fingerprint system to verify the authenticity of the " "server when the client connects. When the user accepts the key's " "fingerprint by typing `yes` when connecting for the first time, a copy of " "the key is saved to [.filename]#.ssh/known_hosts# in the user's home " "directory. Future attempts to login are verified against the saved key and " "`ssh` will display an alert if the server's key does not match the saved " "key. If this occurs, the user should first verify why the key has changed " "before continuing with the connection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1632 msgid "" "Recent versions of OpenSSH only accept SSHv2 connections. SSH protocol " "version 1 is obsolete." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1635 msgid "" "Use man:scp[1] to securely copy a file to or from a remote machine. This " "example copies [.filename]#COPYRIGHT# on the remote system to a file of the " "same name in the current directory of the local system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1643 #, no-wrap msgid "" "# scp user@example.com:/COPYRIGHT COPYRIGHT\n" "Password for user@example.com: *******\n" "COPYRIGHT 100% |*****************************| 4735\n" "00:00\n" "#\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1646 msgid "" "Since the fingerprint was already verified for this host, the server's key " "is automatically checked before prompting for the user's password." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1651 msgid "" "The arguments passed to `scp` are similar to `cp`. The file or files to " "copy is the first argument and the destination to copy to is the second. " "Since the file is fetched over the network, one or more of the file " "arguments takes the form `user@host:`. Be aware when " "copying directories recursively that `scp` uses `-r`, whereas `cp` uses `-R`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1654 msgid "" "To open an interactive session for copying files, use `sftp`. Refer to man:" "sftp[1] for a list of available commands while in an `sftp` session." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/security/_index.adoc:1656 #, no-wrap msgid "Key-based Authentication" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1662 msgid "" "Instead of using passwords, a client can be configured to connect to the " "remote machine using keys. To generate RSA authentication keys, use `ssh-" "keygen`. To generate a public and private key pair, specify the type of key " "and follow the prompts. It is recommended to protect the keys with a " "memorable, but hard to guess passphrase." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1686 #, no-wrap msgid "" "% ssh-keygen -t rsa\n" "Generating public/private rsa key pair.\n" "Enter file in which to save the key (/home/user/.ssh/id_rsa):\n" "Enter passphrase (empty for no passphrase): <.>\n" "Enter same passphrase again: <.>\n" "Your identification has been saved in /home/user/.ssh/id_rsa.\n" "Your public key has been saved in /home/user/.ssh/id_rsa.pub.\n" "The key fingerprint is:\n" "SHA256:54Xm9Uvtv6H4NOo6yjP/YCfODryvUU7yWHzMqeXwhq8 user@host.example.com\n" "The key's randomart image is:\n" "+---[RSA 2048]----+\n" "| |\n" "| |\n" "| |\n" "| . o.. |\n" "| .S*+*o |\n" "| . O=Oo . . |\n" "| = Oo= oo..|\n" "| .oB.* +.oo.|\n" "| =OE**.o..=|\n" "+----[SHA256]-----+\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1689 msgid "Type a passphrase here. It can contain spaces and symbols." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1690 msgid "Retype the passphrase to verify it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1693 msgid "" "The private key is stored in [.filename]#~/.ssh/id_rsa# and the public key " "is stored in [.filename]#~/.ssh/id_rsa.pub#. The _public_ key must be " "copied to [.filename]#~/.ssh/authorized_keys# on the remote machine for key-" "based authentication to work." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1702 msgid "" "Many users believe that keys are secure by design and will use a key without " "a passphrase. This is _dangerous_ behavior. An administrator can verify " "that a key pair is protected by a passphrase by viewing the private key " "manually. If the private key file contains the word `ENCRYPTED`, the key " "owner is using a passphrase. In addition, to better secure end users, " "`from` may be placed in the public key file. For example, adding " "`from=\"192.168.10.5\"` in front of the `ssh-rsa` prefix will only allow " "that specific user to log in from that IP address." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1706 msgid "" "The options and files vary with different versions of OpenSSH. To avoid " "problems, consult man:ssh-keygen[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1709 msgid "" "If a passphrase is used, the user is prompted for the passphrase each time a " "connection is made to the server. To load SSH keys into memory and remove " "the need to type the passphrase each time, use man:ssh-agent[1] and man:ssh-" "add[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1712 msgid "" "Authentication is handled by `ssh-agent`, using the private keys that are " "loaded into it. `ssh-agent` can be used to launch another application like " "a shell or a window manager." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1717 msgid "" "To use `ssh-agent` in a shell, start it with a shell as an argument. Add " "the identity by running `ssh-add` and entering the passphrase for the " "private key. The user will then be able to `ssh` to any host that has the " "corresponding public key installed. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1725 #, no-wrap msgid "" "% ssh-agent csh\n" "% ssh-add\n" "Enter passphrase for key '/usr/home/user/.ssh/id_rsa': <.>\n" "Identity added: /usr/home/user/.ssh/id_rsa (/usr/home/user/.ssh/id_rsa)\n" "%\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1728 msgid "Enter the passphrase for the key." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1732 msgid "" "To use `ssh-agent` in Xorg, add an entry for it in [.filename]#~/.xinitrc#. " "This provides the `ssh-agent` services to all programs launched in Xorg. An " "example [.filename]#~/.xinitrc# might look like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1736 #, no-wrap msgid "exec ssh-agent startxfce4\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1740 msgid "" "This launches `ssh-agent`, which in turn launches XFCE, every time Xorg " "starts. Once Xorg has been restarted so that the changes can take effect, " "run `ssh-add` to load all of the SSH keys." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/security/_index.adoc:1742 #, no-wrap msgid "SSH Tunneling" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1745 msgid "" "OpenSSH has the ability to create a tunnel to encapsulate another protocol " "in an encrypted session." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1747 msgid "The following command tells `ssh` to create a tunnel for telnet:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1752 #, no-wrap msgid "" "% ssh -N -f -L 5023:localhost:23 user@foo.example.com\n" "%\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1755 msgid "This example uses the following options:" msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/security/_index.adoc:1756 #, no-wrap msgid "`-N`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1759 msgid "" "Indicates no command, or tunnel only. If omitted, `ssh` initiates a normal " "session." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/security/_index.adoc:1760 #, no-wrap msgid "`-f`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1762 msgid "Forces `ssh` to run in the background." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/security/_index.adoc:1763 #, no-wrap msgid "`-L`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1765 msgid "Indicates a local tunnel in _localport:remotehost:remoteport_ format." msgstr "" #. type: Labeled list #: documentation/content/en/books/handbook/security/_index.adoc:1766 #, no-wrap msgid "`user@foo.example.com`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1768 msgid "The login name to use on the specified remote SSH server." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1773 msgid "" "An SSH tunnel works by creating a listen socket on `localhost` on the " "specified `localport`. It then forwards any connections received on " "`localport` via the SSH connection to the specified `remotehost:" "remoteport`. In the example, port `5023` on the client is forwarded to port " "`23` on the remote machine. Since port 23 is used by telnet, this creates " "an encrypted telnet session through an SSH tunnel." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1775 msgid "" "This method can be used to wrap any number of insecure TCP protocols such as " "SMTP, POP3, and FTP, as seen in the following examples." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/security/_index.adoc:1776 #, no-wrap msgid "Create a Secure Tunnel for SMTP" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1789 #, no-wrap msgid "" "% ssh -N -f -L 5025:localhost:25 user@mailserver.example.com\n" "user@mailserver.example.com's password: *****\n" "% telnet localhost 5025\n" "Trying 127.0.0.1...\n" "Connected to localhost.\n" "Escape character is '^]'.\n" "220 mailserver.example.com ESMTP\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1792 msgid "" "This can be used in conjunction with `ssh-keygen` and additional user " "accounts to create a more seamless SSH tunneling environment. Keys can be " "used in place of typing a password, and the tunnels can be run as a separate " "user." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/security/_index.adoc:1794 #, no-wrap msgid "Secure Access of a POP3 Server" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1800 msgid "" "In this example, there is an SSH server that accepts connections from the " "outside. On the same network resides a mail server running a POP3 server. " "To check email in a secure manner, create an SSH connection to the SSH " "server and tunnel through to the mail server:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1805 #, no-wrap msgid "" "% ssh -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com\n" "user@ssh-server.example.com's password: ******\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1809 msgid "" "Once the tunnel is up and running, point the email client to send POP3 " "requests to `localhost` on port 2110. This connection will be forwarded " "securely across the tunnel to `mail.example.com`." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/security/_index.adoc:1811 #, no-wrap msgid "Bypassing a Firewall" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1817 msgid "" "Some firewalls filter both incoming and outgoing connections. For example, " "a firewall might limit access from remote machines to ports 22 and 80 to " "only allow SSH and web surfing. This prevents access to any other service " "which uses a port other than 22 or 80." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1819 msgid "" "The solution is to create an SSH connection to a machine outside of the " "network's firewall and use it to tunnel to the desired service:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1824 #, no-wrap msgid "" "% ssh -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org\n" "user@unfirewalled-system.example.org's password: *******\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1827 msgid "" "In this example, a streaming Ogg Vorbis client can now be pointed to " "`localhost` port 8888, which will be forwarded over to `music.example.com` " "on port 8000, successfully bypassing the firewall." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1829 #, no-wrap msgid "Enabling the SSH Server" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1832 msgid "" "In addition to providing built-in SSH client utilities, a FreeBSD system can " "be configured as an SSH server, accepting connections from other SSH clients." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1834 msgid "To see if sshd is operating, use the man:service[8] command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1838 #, no-wrap msgid "# service sshd status\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1841 msgid "" "If the service is not running, add the following line to [.filename]#/etc/rc." "conf#." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1845 #, no-wrap msgid "sshd_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1848 msgid "" "This will start sshd, the daemon program for OpenSSH, the next time the " "system boots. To start it now:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1852 #, no-wrap msgid "# service sshd start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1856 msgid "" "The first time sshd starts on a FreeBSD system, the system's host keys will " "be automatically created and the fingerprint will be displayed on the " "console. Provide users with the fingerprint so that they can verify it the " "first time they connect to the server." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1858 msgid "" "Refer to man:sshd[8] for the list of available options when starting sshd " "and a more complete discussion about authentication, the login process, and " "the various configuration files." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1860 msgid "" "At this point, the sshd should be available to all users with a username and " "password on the system." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1861 #, no-wrap msgid "SSH Server Security" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1865 msgid "" "While sshd is the most widely used remote administration facility for " "FreeBSD, brute force and drive by attacks are common to any system exposed " "to public networks. Several additional parameters are available to prevent " "the success of these attacks and will be described in this section." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1868 msgid "" "It is a good idea to limit which users can log into the SSH server and from " "where using the `AllowUsers` keyword in the OpenSSH server configuration " "file. For example, to only allow `root` to log in from `192.168.1.32`, add " "this line to [.filename]#/etc/ssh/sshd_config#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1872 #, no-wrap msgid "AllowUsers root@192.168.1.32\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1875 msgid "" "To allow `admin` to log in from anywhere, list that user without specifying " "an IP address:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1879 #, no-wrap msgid "AllowUsers admin\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1882 msgid "Multiple users should be listed on the same line, like so:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1886 #, no-wrap msgid "AllowUsers root@192.168.1.32 admin\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1889 msgid "" "After making changes to [.filename]#/etc/ssh/sshd_config#, tell sshd to " "reload its configuration file by running:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1893 #, no-wrap msgid "# service sshd reload\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1903 msgid "" "When this keyword is used, it is important to list each user that needs to " "log into this machine. Any user that is not specified in that line will be " "locked out. Also, the keywords used in the OpenSSH server configuration " "file are case-sensitive. If the keyword is not spelled correctly, including " "its case, it will be ignored. Always test changes to this file to make sure " "that the edits are working as expected. Refer to man:sshd_config[5] to " "verify the spelling and use of the available keywords." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1909 msgid "" "In addition, users may be forced to use two factor authentication via the " "use of a public and private key. When required, the user may generate a key " "pair through the use of man:ssh-keygen[1] and send the administrator the " "public key. This key file will be placed in the [." "filename]#authorized_keys# as described above in the client section. To " "force the users to use keys only, the following option may be configured:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1913 #, no-wrap msgid "AuthenticationMethods publickey\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1921 msgid "" "Do not confuse [.filename]#/etc/ssh/sshd_config# with [.filename]#/etc/ssh/" "ssh_config# (note the extra `d` in the first filename). The first file " "configures the server and the second file configures the client. Refer to " "man:ssh_config[5] for a listing of the available client settings." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:1924 #, no-wrap msgid "Access Control Lists" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1928 msgid "" "Access Control Lists (ACLs) extend the standard UNIX(R) permission model in " "a POSIX(R).1e compatible way. This permits an administrator to take " "advantage of a more fine-grained permissions model." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1931 msgid "" "The FreeBSD [.filename]#GENERIC# kernel provides ACL support for UFS file " "systems. Users who prefer to compile a custom kernel must include the " "following option in their custom kernel configuration file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1935 #, no-wrap msgid "options UFS_ACL\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1939 msgid "" "If this option is not compiled in, a warning message will be displayed when " "attempting to mount a file system with ACL support. ACLs rely on extended " "attributes which are natively supported in UFS2." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1941 msgid "" "This chapter describes how to enable ACL support and provides some usage " "examples." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1942 #, no-wrap msgid "Enabling ACL Support" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1947 msgid "" "ACLs are enabled by the mount-time administrative flag, `acls`, which may be " "added to [.filename]#/etc/fstab#. The mount-time flag can also be " "automatically set in a persistent manner using man:tunefs[8] to modify a " "superblock ACLs flag in the file system header. In general, it is preferred " "to use the superblock flag for several reasons:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1949 msgid "" "The superblock flag cannot be changed by a remount using `mount -u` as it " "requires a complete `umount` and fresh `mount`. This means that ACLs cannot " "be enabled on the root file system after boot. It also means that ACL " "support on a file system cannot be changed while the system is in use." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1950 msgid "" "Setting the superblock flag causes the file system to always be mounted with " "ACLs enabled, even if there is not an [.filename]#fstab# entry or if the " "devices re-order. This prevents accidental mounting of the file system " "without ACL support." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:1955 msgid "" "It is desirable to discourage accidental mounting without ACLs enabled " "because nasty things can happen if ACLs are enabled, then disabled, then re-" "enabled without flushing the extended attributes. In general, once ACLs are " "enabled on a file system, they should not be disabled, as the resulting file " "protections may not be compatible with those intended by the users of the " "system, and re-enabling ACLs may re-attach the previous ACLs to files that " "have since had their permissions changed, resulting in unpredictable " "behavior." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1958 msgid "" "File systems with ACLs enabled will show a plus (`+`) sign in their " "permission settings:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1966 #, no-wrap msgid "" "drwx------ 2 robert robert 512 Dec 27 11:54 private\n" "drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1\n" "drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2\n" "drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3\n" "drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1969 msgid "" "In this example, [.filename]#directory1#, [.filename]#directory2#, and [." "filename]#directory3# are all taking advantage of ACLs, whereas [." "filename]#private# and [.filename]#public_html# are not." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:1970 #, no-wrap msgid "Using ACLs" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1974 msgid "" "File system ACLs can be viewed using `getfacl`. For instance, to view the " "ACL settings on [.filename]#test#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1984 #, no-wrap msgid "" "% getfacl test\n" "\t#file:test\n" "\t#owner:1001\n" "\t#group:1001\n" "\tuser::rw-\n" "\tgroup::r--\n" "\tother::r--\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1989 msgid "" "To change the ACL settings on this file, use `setfacl`. To remove all of " "the currently defined ACLs from a file or file system, include `-k`. " "However, the preferred method is to use `-b` as it leaves the basic fields " "required for ACLs to work." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:1993 #, no-wrap msgid "% setfacl -k test\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:1996 msgid "To modify the default ACL entries, use `-m`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2000 #, no-wrap msgid "% setfacl -m u:trhodes:rwx,group:web:r--,o::--- test\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2005 msgid "" "In this example, there were no pre-defined entries, as they were removed by " "the previous command. This command restores the default options and assigns " "the options listed. If a user or group is added which does not exist on the " "system, an `Invalid argument` error will be displayed." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2007 msgid "" "Refer to man:getfacl[1] and man:setfacl[1] for more information about the " "options available for these commands." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2009 #, no-wrap msgid "Monitoring Third Party Security Issues" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2013 msgid "" "In recent years, the security world has made many improvements to how " "vulnerability assessment is handled. The threat of system intrusion " "increases as third party utilities are installed and configured for " "virtually any operating system available today." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2018 msgid "" "Vulnerability assessment is a key factor in security. While FreeBSD " "releases advisories for the base system, doing so for every third party " "utility is beyond the FreeBSD Project's capability. There is a way to " "mitigate third party vulnerabilities and warn administrators of known " "security issues. A FreeBSD add on utility known as pkg includes options " "explicitly for this purpose." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2021 msgid "" "pkg polls a database for security issues. The database is updated and " "maintained by the FreeBSD Security Team and ports developers." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2023 msgid "" "Please refer to crossref:ports[pkgng-intro,instructions] for installing pkg." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2027 msgid "" "Installation provides man:periodic[8] configuration files for maintaining " "the pkg audit database, and provides a programmatic method of keeping it " "updated. This functionality is enabled if " "`daily_status_security_pkgaudit_enable` is set to `YES` in man:periodic." "conf[5]. Ensure that daily security run emails, which are sent to " "``root``'s email account, are being read." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2029 msgid "" "After installation, and to audit third party utilities as part of the Ports " "Collection at any time, an administrator may choose to update the database " "and view known vulnerabilities of installed packages by invoking:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2033 #, no-wrap msgid "# pkg audit -F\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2036 msgid "" "pkg displays messages any published vulnerabilities in installed packages:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2042 #, no-wrap msgid "" "Affected package: cups-base-1.1.22.0_1\n" "Type of problem: cups-base -- HPGL buffer overflow vulnerability.\n" "Reference: \n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2044 #, no-wrap msgid "1 problem(s) in your installed packages found.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2046 #, no-wrap msgid "You are advised to update or deinstall the affected package(s) immediately.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2050 msgid "" "By pointing a web browser to the displayed URL, an administrator may obtain " "more information about the vulnerability. This will include the versions " "affected, by FreeBSD port version, along with other web sites which may " "contain security advisories." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2052 msgid "" "pkg is a powerful utility and is extremely useful when coupled with package:" "ports-mgmt/portmaster[]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2054 #, no-wrap msgid "FreeBSD Security Advisories" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2058 msgid "" "Like many producers of quality operating systems, the FreeBSD Project has a " "security team which is responsible for determining the End-of-Life (EoL) " "date for each FreeBSD release and to provide security updates for supported " "releases which have not yet reached their EoL. More information about the " "FreeBSD security team and the supported releases is available on the link:" "https://www.FreeBSD.org/security[FreeBSD security page]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2063 msgid "" "One task of the security team is to respond to reported security " "vulnerabilities in the FreeBSD operating system. Once a vulnerability is " "confirmed, the security team verifies the steps necessary to fix the " "vulnerability and updates the source code with the fix. It then publishes " "the details as a \"Security Advisory\". Security advisories are published " "on the link:https://www.FreeBSD.org/security/advisories/[FreeBSD website] " "and mailed to the {freebsd-security-notifications}, {freebsd-security}, and " "{freebsd-announce} mailing lists." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2065 msgid "This section describes the format of a FreeBSD security advisory." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:2066 #, no-wrap msgid "Format of a Security Advisory" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2069 msgid "Here is an example of a FreeBSD security advisory:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2075 #, no-wrap msgid "" "=============================================================================\n" "-----BEGIN PGP SIGNED MESSAGE-----\n" "Hash: SHA512\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2079 #, no-wrap msgid "" "=============================================================================\n" "FreeBSD-SA-14:04.bind Security Advisory\n" " The FreeBSD Project\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2081 #, no-wrap msgid "Topic: BIND remote denial of service vulnerability\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2094 #, no-wrap msgid "" "Category: contrib\n" "Module: bind\n" "Announced: 2014-01-14\n" "Credits: ISC\n" "Affects: FreeBSD 8.x and FreeBSD 9.x\n" "Corrected: 2014-01-14 19:38:37 UTC (stable/9, 9.2-STABLE)\n" " 2014-01-14 19:42:28 UTC (releng/9.2, 9.2-RELEASE-p3)\n" " 2014-01-14 19:42:28 UTC (releng/9.1, 9.1-RELEASE-p10)\n" " 2014-01-14 19:38:37 UTC (stable/8, 8.4-STABLE)\n" " 2014-01-14 19:42:28 UTC (releng/8.4, 8.4-RELEASE-p7)\n" " 2014-01-14 19:42:28 UTC (releng/8.3, 8.3-RELEASE-p14)\n" "CVE Name: CVE-2014-0591\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2098 #, no-wrap msgid "" "For general information regarding FreeBSD Security Advisories,\n" "including descriptions of the fields above, security branches, and the\n" "following sections, please visit .\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2100 #, no-wrap msgid "I. Background\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2103 #, no-wrap msgid "" "BIND 9 is an implementation of the Domain Name System (DNS) protocols.\n" "The named(8) daemon is an Internet Domain Name Server.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2105 #, no-wrap msgid "II. Problem Description\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2110 #, no-wrap msgid "" "Because of a defect in handling queries for NSEC3-signed zones, BIND can\n" "crash with an \"INSIST\" failure in name.c when processing queries possessing\n" "certain properties. This issue only affects authoritative nameservers with\n" "at least one NSEC3-signed zone. Recursive-only servers are not at risk.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2112 #, no-wrap msgid "III. Impact\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2115 #, no-wrap msgid "" "An attacker who can send a specially crafted query could cause named(8)\n" "to crash, resulting in a denial of service.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2117 #, no-wrap msgid "IV. Workaround\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2120 #, no-wrap msgid "" "No workaround is available, but systems not running authoritative DNS service\n" "with at least one NSEC3-signed zone using named(8) are not vulnerable.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2122 #, no-wrap msgid "V. Solution\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2124 #, no-wrap msgid "Perform one of the following:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2127 #, no-wrap msgid "" "1) Upgrade your vulnerable system to a supported FreeBSD stable or\n" "release / security branch (releng) dated after the correction date.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2129 #, no-wrap msgid "2) To update your vulnerable system via a source code patch:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2132 #, no-wrap msgid "" "The following patches have been verified to apply to the applicable\n" "FreeBSD release branches.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2135 #, no-wrap msgid "" "a) Download the relevant patch from the location below, and verify the\n" "detached PGP signature using your PGP utility.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2140 #, no-wrap msgid "" "[FreeBSD 8.3, 8.4, 9.1, 9.2-RELEASE and 8.4-STABLE]\n" "# fetch http://security.FreeBSD.org/patches/SA-14:04/bind-release.patch\n" "# fetch http://security.FreeBSD.org/patches/SA-14:04/bind-release.patch.asc\n" "# gpg --verify bind-release.patch.asc\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2145 #, no-wrap msgid "" "[FreeBSD 9.2-STABLE]\n" "# fetch http://security.FreeBSD.org/patches/SA-14:04/bind-stable-9.patch\n" "# fetch http://security.FreeBSD.org/patches/SA-14:04/bind-stable-9.patch.asc\n" "# gpg --verify bind-stable-9.patch.asc\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2147 #, no-wrap msgid "b) Execute the following commands as root:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2150 #, no-wrap msgid "" "# cd /usr/src\n" "# patch < /path/to/patch\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2153 #, no-wrap msgid "" "Recompile the operating system using buildworld and installworld as\n" "described in .\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2155 #, no-wrap msgid "Restart the applicable daemons, or reboot the system.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2157 #, no-wrap msgid "3) To update your vulnerable system via a binary patch:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2160 #, no-wrap msgid "" "Systems running a RELEASE version of FreeBSD on the i386 or amd64\n" "platforms can be updated via the man:freebsd-update[8] utility:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2163 #, no-wrap msgid "" "# freebsd-update fetch\n" "# freebsd-update install\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2165 #, no-wrap msgid "VI. Correction details\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2168 #, no-wrap msgid "" "The following list contains the correction revision numbers for each\n" "affected branch.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2178 #, no-wrap msgid "" "Branch/path Revision\n" "- -------------------------------------------------------------------------\n" "stable/8/ r260646\n" "releng/8.3/ r260647\n" "releng/8.4/ r260647\n" "stable/9/ r260646\n" "releng/9.1/ r260647\n" "releng/9.2/ r260647\n" "- -------------------------------------------------------------------------\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2182 #, no-wrap msgid "" "To see which files were modified by a particular revision, run the\n" "following command, replacing NNNNNN with the revision number, on a\n" "machine with Subversion installed:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2184 #, no-wrap msgid "# svn diff -cNNNNNN --summarize svn://svn.freebsd.org/base\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2186 #, no-wrap msgid "Or visit the following URL, replacing NNNNNN with the revision number:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2188 #, no-wrap msgid "\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2190 #, no-wrap msgid "VII. References\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2192 #, no-wrap msgid "\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2194 #, no-wrap msgid "\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2198 #, no-wrap msgid "" "The latest revision of this advisory is available at\n" "\n" "-----BEGIN PGP SIGNATURE-----\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2213 #, no-wrap msgid "" "iQIcBAEBCgAGBQJS1ZTYAAoJEO1n7NZdz2rnOvQP/2/68/s9Cu35PmqNtSZVVxVG\n" "ZSQP5EGWx/lramNf9566iKxOrLRMq/h3XWcC4goVd+gZFrvITJSVOWSa7ntDQ7TO\n" "XcinfRZ/iyiJbs/Rg2wLHc/t5oVSyeouyccqODYFbOwOlk35JjOTMUG1YcX+Zasg\n" "ax8RV+7Zt1QSBkMlOz/myBLXUjlTZ3Xg2FXVsfFQW5/g2CjuHpRSFx1bVNX6ysoG\n" "9DT58EQcYxIS8WfkHRbbXKh9I1nSfZ7/Hky/kTafRdRMrjAgbqFgHkYTYsBZeav5\n" "fYWKGQRJulYfeZQ90yMTvlpF42DjCC3uJYamJnwDIu8OhS1WRBI8fQfr9DRzmRua\n" "OK3BK9hUiScDZOJB6OqeVzUTfe7MAA4/UwrDtTYQ+PqAenv1PK8DZqwXyxA9ThHb\n" "zKO3OwuKOVHJnKvpOcr+eNwo7jbnHlis0oBksj/mrq2P9m2ueF9gzCiq5Ri5Syag\n" "Wssb1HUoMGwqU0roS8+pRpNC8YgsWpsttvUWSZ8u6Vj/FLeHpiV3mYXPVMaKRhVm\n" "067BA2uj4Th1JKtGleox+Em0R7OFbCc/9aWC67wiqI6KRyit9pYiF3npph+7D5Eq\n" "7zPsUdDd+qc+UTiLp3liCRp5w6484wWdhZO6wRtmUgxGjNkxFoNnX8CitzF8AaqO\n" "UWWemqWuz3lAZuORQ9KX\n" "=OQzQ\n" "-----END PGP SIGNATURE-----\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2216 msgid "Every security advisory uses the following format:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2218 msgid "" "Each security advisory is signed by the PGP key of the Security Officer. The " "public key for the Security Officer can be verified at crossref:" "pgpkeys[pgpkeys,OpenPGP Keys]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2219 msgid "" "The name of the security advisory always begins with `FreeBSD-SA-` (for " "FreeBSD Security Advisory), followed by the year in two digit format (`14:" "`), followed by the advisory number for that year (`04.`), followed by the " "name of the affected application or subsystem (`bind`). The advisory shown " "here is the fourth advisory for 2014 and it affects BIND." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2220 msgid "The `Topic` field summarizes the vulnerability." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2221 msgid "" "The `Category` refers to the affected part of the system which may be one of " "`core`, `contrib`, or `ports`. The `core` category means that the " "vulnerability affects a core component of the FreeBSD operating system. The " "`contrib` category means that the vulnerability affects software included " "with FreeBSD, such as BIND. The `ports` category indicates that the " "vulnerability affects software available through the Ports Collection." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2222 msgid "" "The `Module` field refers to the component location. In this example, the " "`bind` module is affected; therefore, this vulnerability affects an " "application installed with the operating system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2223 msgid "" "The `Announced` field reflects the date the security advisory was published. " "This means that the security team has verified that the problem exists and " "that a patch has been committed to the FreeBSD source code repository." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2224 msgid "" "The `Credits` field gives credit to the individual or organization who " "noticed the vulnerability and reported it." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2225 msgid "" "The `Affects` field explains which releases of FreeBSD are affected by this " "vulnerability." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2226 msgid "" "The `Corrected` field indicates the date, time, time offset, and releases " "that were corrected. The section in parentheses shows each branch for which " "the fix has been merged, and the version number of the corresponding release " "from that branch. The release identifier itself includes the version number " "and, if appropriate, the patch level. The patch level is the letter `p` " "followed by a number, indicating the sequence number of the patch, allowing " "users to track which patches have already been applied to the system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2227 msgid "" "The `CVE Name` field lists the advisory number, if one exists, in the public " "http://cve.mitre.org[cve.mitre.org] security vulnerabilities database." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2228 msgid "The `Background` field provides a description of the affected module." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2229 msgid "" "The `Problem Description` field explains the vulnerability. This can include " "information about the flawed code and how the utility could be maliciously " "used." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2230 msgid "" "The `Impact` field describes what type of impact the problem could have on a " "system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2231 msgid "" "The `Workaround` field indicates if a workaround is available to system " "administrators who cannot immediately patch the system ." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2232 msgid "" "The `Solution` field provides the instructions for patching the affected " "system. This is a step by step tested and verified method for getting a " "system patched and working securely." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2233 msgid "" "The `Correction Details` field displays each affected Subversion branch with " "the revision number that contains the corrected code." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2234 msgid "" "The `References` field offers sources of additional information regarding " "the vulnerability." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2236 #, no-wrap msgid "Process Accounting" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2239 msgid "" "Process accounting is a security method in which an administrator may keep " "track of system resources used and their allocation among users, provide for " "system monitoring, and minimally track a user's commands." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2244 msgid "" "Process accounting has both positive and negative points. One of the " "positives is that an intrusion may be narrowed down to the point of entry. " "A negative is the amount of logs generated by process accounting, and the " "disk space they may require. This section walks an administrator through " "the basics of process accounting." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2248 msgid "" "If more fine-grained accounting is needed, refer to crossref:audit[audit," "Security Event Auditing]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:2250 #, no-wrap msgid "Enabling and Utilizing Process Accounting" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2253 msgid "" "Before using process accounting, it must be enabled using the following " "commands:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2258 #, no-wrap msgid "" "# sysrc accounting_enable=yes\n" "# service accounting start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2264 msgid "" "The accounting information is stored in files located in [.filename]#/var/" "account#, which is automatically created, if necessary, the first time the " "accounting service starts. These files contain sensitive information, " "including all the commands issued by all users. Write access to the files " "is limited to `root`, and read access is limited to `root` and members of " "the `wheel` group. To also prevent members of `wheel` from reading the " "files, change the mode of the [.filename]#/var/account# directory to allow " "access only by `root`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2269 msgid "" "Once enabled, accounting will begin to track information such as CPU " "statistics and executed commands. All accounting logs are in a non-human " "readable format which can be viewed using `sa`. If issued without any " "options, `sa` prints information relating to the number of per-user calls, " "the total elapsed time in minutes, total CPU and user time in minutes, and " "the average number of I/O operations. Refer to man:sa[8] for the list of " "available options which control the output." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2272 msgid "" "To display the commands issued by users, use `lastcomm`. For example, this " "command prints out all usage of `ls` by `trhodes` on the `ttyp1` terminal:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2276 #, no-wrap msgid "# lastcomm ls trhodes ttyp1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2279 msgid "" "Many other useful options exist and are explained in man:lastcomm[1], man:" "acct[5], and man:sa[8]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2281 #, no-wrap msgid "Resource Limits" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2286 msgid "" "FreeBSD provides several methods for an administrator to limit the amount of " "system resources an individual may use. Disk quotas limit the amount of " "disk space available to users. Quotas are discussed in crossref:" "disks[quotas,\"Disk Quotas\"]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2291 msgid "" "Limits to other resources, such as CPU and memory, can be set using either a " "flat file or a command to configure a resource limits database. The " "traditional method defines login classes by editing [.filename]#/etc/login." "conf#. While this method is still supported, any changes require a multi-" "step process of editing this file, rebuilding the resource database, making " "necessary changes to [.filename]#/etc/master.passwd#, and rebuilding the " "password database. This can become time consuming, depending upon the " "number of users to configure." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2294 msgid "" "`rctl` can be used to provide a more fine-grained method for controlling " "resource limits. This command supports more than user limits as it can also " "be used to set resource constraints on processes and jails." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2296 msgid "" "This section demonstrates both methods for controlling resources, beginning " "with the traditional method." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:2298 #, no-wrap msgid "Configuring Login Classes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2304 msgid "" "In the traditional method, login classes and the resource limits to apply to " "a login class are defined in [.filename]#/etc/login.conf#. Each user " "account can be assigned to a login class, where `default` is the default " "login class. Each login class has a set of login capabilities associated " "with it. A login capability is a `_name_=_value_` pair, where _name_ is a " "well-known identifier and _value_ is an arbitrary string which is processed " "accordingly depending on the _name_." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2308 msgid "" "Whenever [.filename]#/etc/login.conf# is edited, the [.filename]#/etc/login." "conf.db# must be updated by executing the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2312 #, no-wrap msgid "# cap_mkdb /etc/login.conf\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2321 msgid "" "Resource limits differ from the default login capabilities in two ways. " "First, for every limit, there is a _soft_ and _hard_ limit. A soft limit " "may be adjusted by the user or application, but may not be set higher than " "the hard limit. The hard limit may be lowered by the user, but can only be " "raised by the superuser. Second, most resource limits apply per process to " "a specific user." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2324 msgid "" "<> lists the most commonly used resource limits. All of " "the available resource limits and capabilities are described in detail in " "man:login.conf[5]." msgstr "" #. type: Block title #: documentation/content/en/books/handbook/security/_index.adoc:2326 #, no-wrap msgid "Login Class Resource Limits" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2330 #, no-wrap msgid "Resource Limit" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2332 #, no-wrap msgid "Description" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2333 #, no-wrap msgid "coredumpsize" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2335 #, no-wrap msgid "The limit on the size of a core file generated by a program is subordinate to other limits on disk usage, such as `filesize` or disk quotas. This limit is often used as a less severe method of controlling disk space consumption. Since users do not generate core files and often do not delete them, this setting may save them from running out of disk space should a large program crash." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2336 #, no-wrap msgid "cputime" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2338 #, no-wrap msgid "The maximum amount of CPU time a user's process may consume. Offending processes will be killed by the kernel. This is a limit on CPU _time_ consumed, not the percentage of the CPU as displayed in some of the fields generated by `top` and `ps`." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2339 #, no-wrap msgid "filesize" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2341 #, no-wrap msgid "The maximum size of a file the user may own. Unlike disk quotas (crossref:disks[quotas,\"Disk Quotas\"]), this limit is enforced on individual files, not the set of all files a user owns." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2342 #, no-wrap msgid "maxproc" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2344 #, no-wrap msgid "The maximum number of foreground and background processes a user can run. This limit may not be larger than the system limit specified by `kern.maxproc`. Setting this limit too small may hinder a user's productivity as some tasks, such as compiling a large program, start lots of processes." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2345 #, no-wrap msgid "memorylocked" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2347 #, no-wrap msgid "The maximum amount of memory a process may request to be locked into main memory using man:mlock[2]. Some system-critical programs, such as man:amd[8], lock into main memory so that if the system begins to swap, they do not contribute to disk thrashing." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2348 #, no-wrap msgid "memoryuse" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2350 #, no-wrap msgid "The maximum amount of memory a process may consume at any given time. It includes both core memory and swap usage. This is not a catch-all limit for restricting memory consumption, but is a good start." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2351 #, no-wrap msgid "openfiles" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2353 #, no-wrap msgid "The maximum number of files a process may have open. In FreeBSD, files are used to represent sockets and IPC channels, so be careful not to set this too low. The system-wide limit for this is defined by `kern.maxfiles`." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2354 #, no-wrap msgid "sbsize" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2356 #, no-wrap msgid "The limit on the amount of network memory a user may consume. This can be generally used to limit network communications." msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2357 #, no-wrap msgid "stacksize" msgstr "" #. type: Table #: documentation/content/en/books/handbook/security/_index.adoc:2358 #, no-wrap msgid "The maximum size of a process stack. This alone is not sufficient to limit the amount of memory a program may use, so it should be used in conjunction with other limits." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2361 msgid "There are a few other things to remember when setting resource limits:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2363 msgid "" "Processes started at system startup by [.filename]#/etc/rc# are assigned to " "the `daemon` login class." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2364 msgid "" "Although the default [.filename]#/etc/login.conf# is a good source of " "reasonable values for most limits, they may not be appropriate for every " "system. Setting a limit too high may open the system up to abuse, while " "setting it too low may put a strain on productivity." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2365 msgid "" "Xorg takes a lot of resources and encourages users to run more programs " "simultaneously." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2366 msgid "" "Many limits apply to individual processes, not the user as a whole. For " "example, setting `openfiles` to `50` means that each process the user runs " "may open up to `50` files. The total amount of files a user may open is the " "value of `openfiles` multiplied by the value of `maxproc`. This also applies " "to memory consumption." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2368 msgid "" "For further information on resource limits and login classes and " "capabilities in general, refer to man:cap.mkdb[1], man:getrlimit[2], and man:" "login.conf[5]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:2369 #, no-wrap msgid "Enabling and Configuring Resource Limits" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2373 msgid "" "The `kern.racct.enable` tunable must be set to a non-zero value. Custom " "kernels require specific configuration:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2378 #, no-wrap msgid "" "options RACCT\n" "options RCTL\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2381 msgid "" "Once the system has rebooted into the new kernel, `rctl` may be used to set " "rules for the system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2383 msgid "" "Rule syntax is controlled through the use of a subject, subject-id, " "resource, and action, as seen in this example rule:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2387 #, no-wrap msgid "user:trhodes:maxproc:deny=10/user\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2392 msgid "" "In this rule, the subject is `user`, the subject-id is `trhodes`, the " "resource, `maxproc`, is the maximum number of processes, and the action is " "`deny`, which blocks any new processes from being created. This means that " "the user, `trhodes`, will be constrained to no greater than `10` processes. " "Other possible actions include logging to the console, passing a " "notification to man:devd[8], or sending a sigterm to the process." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2396 msgid "" "Some care must be taken when adding rules. Since this user is constrained " "to `10` processes, this example will prevent the user from performing other " "tasks after logging in and executing a `screen` session. Once a resource " "limit has been hit, an error will be printed, as in this example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2402 #, no-wrap msgid "" "% man test\n" " /usr/bin/man: Cannot fork: Resource temporarily unavailable\n" "eval: Cannot fork: Resource temporarily unavailable\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2406 msgid "" "As another example, a jail can be prevented from exceeding a memory limit. " "This rule could be written as:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2410 #, no-wrap msgid "# rctl -a jail:httpd:memoryuse:deny=2G/jail\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2414 msgid "" "Rules will persist across reboots if they have been added to [.filename]#/" "etc/rctl.conf#. The format is a rule, without the preceding command. For " "example, the previous rule could be added as:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2419 #, no-wrap msgid "" "# Block jail from using more than 2G memory:\n" "jail:httpd:memoryuse:deny=2G/jail\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2422 msgid "To remove a rule, use `rctl` to remove it from the list:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2426 #, no-wrap msgid "# rctl -r user:trhodes:maxproc:deny=10/user\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2430 msgid "" "A method for removing all rules is documented in man:rctl[8]. However, if " "removing all rules for a single user is required, this command may be issued:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2434 #, no-wrap msgid "# rctl -r user:trhodes\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2438 msgid "" "Many other resources exist which can be used to exert additional control " "over various `subjects`. See man:rctl[8] to learn about them." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2440 #, no-wrap msgid "Shared Administration with Sudo" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2446 msgid "" "System administrators often need the ability to grant enhanced permissions " "to users so they may perform privileged tasks. The idea that team members " "are provided access to a FreeBSD system to perform their specific tasks " "opens up unique challenges to every administrator. These team members only " "need a subset of access beyond normal end user levels; however, they almost " "always tell management they are unable to perform their tasks without " "superuser access. Thankfully, there is no reason to provide such access to " "end users because tools exist to manage this exact requirement." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2453 msgid "" "Up to this point, the security chapter has covered permitting access to " "authorized users and attempting to prevent unauthorized access. Another " "problem arises once authorized users have access to the system resources. " "In many cases, some users may need access to application startup scripts, or " "a team of administrators need to maintain the system. Traditionally, the " "standard users and groups, file permissions, and even the man:su[1] command " "would manage this access. And as applications required more access, as more " "users needed to use system resources, a better solution was required. The " "most used application is currently Sudo." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2457 msgid "" "Sudo allows administrators to configure more rigid access to system commands " "and provide for some advanced logging features. As a tool, it is available " "from the Ports Collection as package:security/sudo[] or by use of the man:" "pkg[8] utility. To use the man:pkg[8] tool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2461 #, no-wrap msgid "# pkg install sudo\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2465 msgid "" "After the installation is complete, the installed `visudo` will open the " "configuration file with a text editor. Using `visudo` is highly recommended " "as it comes with a built in syntax checker to verify there are no errors " "before the file is saved." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2469 msgid "" "The configuration file is made up of several small sections which allow for " "extensive configuration. In the following example, web application " "maintainer, user1, needs to start, stop, and restart the web application " "known as _webservice_. To grant this user permission to perform these " "tasks, add this line to the end of [.filename]#/usr/local/etc/sudoers#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2473 #, no-wrap msgid "user1 ALL=(ALL) /usr/sbin/service webservice *\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2476 msgid "The user may now start _webservice_ using this command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2480 #, no-wrap msgid "% sudo /usr/sbin/service webservice start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2486 msgid "" "While this configuration allows a single user access to the webservice " "service; however, in most organizations, there is an entire web team in " "charge of managing the service. A single line can also give access to an " "entire group. These steps will create a web group, add a user to this " "group, and allow all members of the group to manage the service:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2490 #, no-wrap msgid "# pw groupadd -g 6001 -n webteam\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2493 msgid "" "Using the same man:pw[8] command, the user is added to the webteam group:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2497 #, no-wrap msgid "# pw groupmod -m user1 -n webteam\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2500 msgid "" "Finally, this line in [.filename]#/usr/local/etc/sudoers# allows any member " "of the webteam group to manage _webservice_:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2504 #, no-wrap msgid "%webteam ALL=(ALL) /usr/sbin/service webservice *\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2509 msgid "" "Unlike man:su[1], Sudo only requires the end user password. This adds an " "advantage where users will not need shared passwords, a finding in most " "security audits and just bad all the way around." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2513 msgid "" "Users permitted to run applications with Sudo only enter their own " "passwords. This is more secure and gives better control than man:su[1], " "where the `root` password is entered and the user acquires all `root` " "permissions." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2521 msgid "" "Most organizations are moving or have moved toward a two factor " "authentication model. In these cases, the user may not have a password to " "enter. Sudo provides for these cases with the `NOPASSWD` variable. Adding " "it to the configuration above will allow all members of the _webteam_ group " "to manage the service without the password requirement:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2525 #, no-wrap msgid "%webteam ALL=(ALL) NOPASSWD: /usr/sbin/service webservice *\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/security/_index.adoc:2530 #, no-wrap msgid "Logging Output" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2537 msgid "" "An advantage to implementing Sudo is the ability to enable session logging. " "Using the built in log mechanisms and the included sudoreplay command, all " "commands initiated through Sudo are logged for later verification. To " "enable this feature, add a default log directory entry, this example uses a " "user variable. Several other log filename conventions exist, consult the " "manual page for sudoreplay for additional information." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2541 #, no-wrap msgid "Defaults iolog_dir=/var/log/sudo-io/%{user}\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2550 msgid "" "This directory will be created automatically after the logging is " "configured. It is best to let the system create directory with default " "permissions just to be safe. In addition, this entry will also log " "administrators who use the sudoreplay command. To change this behavior, " "read and uncomment the logging options inside [.filename]#sudoers#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2554 msgid "" "Once this directive has been added to the [.filename]#sudoers# file, any " "user configuration can be updated with the request to log access. In the " "example shown, the updated _webteam_ entry would have the following " "additional changes:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2558 #, no-wrap msgid "%webteam ALL=(ALL) NOPASSWD: LOG_INPUT: LOG_OUTPUT: /usr/sbin/service webservice *\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2562 msgid "" "From this point on, all _webteam_ members altering the status of the " "_webservice_ application will be logged. The list of previous and current " "sessions can be displayed with:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2566 #, no-wrap msgid "# sudoreplay -l\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2570 msgid "" "In the output, to replay a specific session, search for the `TSID=` entry, " "and pass that to sudoreplay with no other options to replay the session at " "normal speed. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2574 #, no-wrap msgid "# sudoreplay user1/00/00/02\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/security/_index.adoc:2581 msgid "" "While sessions are logged, any administrator is able to remove sessions and " "leave only a question of why they had done so. It is worthwhile to add a " "daily check through an intrusion detection system (IDS) or similar software " "so that other administrators are alerted to manual alterations." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2585 msgid "" "The `sudoreplay` is extremely extendable. Consult the documentation for " "more information." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/security/_index.adoc:2587 #, no-wrap msgid "Using doas as an alternative to sudo" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2590 msgid "" "As an alternative to package:security/sudo[] package:security/doas[] can be " "used to provide the ability for users to get enhanced privileges." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2592 msgid "" "The doas utility is available via the ports collection in package:security/" "doas[] or via the man:pkg[8] utility." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2594 msgid "" "After the installation [.filename]#/usr/local/etc/doas.conf# must be " "configured to grant access for users for specific commands, or roles." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2596 msgid "" "The simpliest entry could be the following, which grants local_user root " "permissions without asking for its password when executing the doas command." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2600 #, no-wrap msgid "permit nopass local_user as root\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2603 msgid "For more configuration examples, please read man:doas.conf[5]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/security/_index.adoc:2605 msgid "" "After the installation and configuration of the `doas` utility, a command " "can now be executed with enhanced privileges, like for example." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/security/_index.adoc:2609 #, no-wrap msgid "$ doas vi /etc/rc.conf\n" msgstr "" diff --git a/documentation/content/en/books/porters-handbook/pkg-files/_index.po b/documentation/content/en/books/porters-handbook/pkg-files/_index.po index 7a15bf5c2f..0b01f71f10 100644 --- a/documentation/content/en/books/porters-handbook/pkg-files/_index.po +++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.po @@ -1,681 +1,698 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" -"POT-Creation-Date: 2023-01-21 20:00-0300\n" +"POT-Creation-Date: 2023-06-19 21:08-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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/books/porters-handbook/pkg-files/_index.adoc:1 #, no-wrap msgid "Tricks about the pkg-* files" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:1 #, no-wrap msgid "Chapter 9. pkg-*" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:13 #, no-wrap msgid "pkg-*" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:51 msgid "" "There are some tricks we have not mentioned yet about the [.filename]#pkg-*# " "files that come in handy sometimes." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:53 #, no-wrap msgid "pkg-message" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:57 msgid "" "To display a message when the package is installed, place the message in [." "filename]#pkg-message#. This capability is often useful to display " "additional installation steps to be taken after a `pkg install` or `pkg " "upgrade`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:61 msgid "" "[.filename]#pkg-message# must contain only information that is _vital_ to " "setup and operation on FreeBSD, and that is unique to the port in question." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:62 msgid "" "Setup information should only be shown on initial install. Upgrade " "instructions should be shown only when upgrading from the relevant version." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:63 msgid "" "Do not surround the messages with either whitespace or lines of symbols " "(like `----------`, `**********`, or `==========`). Leave the formatting to " "man:pkg[8]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:64 msgid "" "Committers have blanket approval to constrain existing messages to install " "or upgrade ranges using the UCL format specifications." msgstr "" +#. type: delimited block = 4 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:65 +msgid "Please be sure to refer to the proper tools for handling services." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:66 +msgid "" +"Use `service name start` to start a service rather than using `/usr/local/" +"etc/rc.d/name start`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:67 +msgid "Use `sysrc name_enable=YES` to change options in rc.conf" +msgstr "" + #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:68 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:71 msgid "pkg-message supports two formats:" msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:69 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:72 #, no-wrap msgid "raw" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:72 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:75 msgid "A regular plain text file. Its message is only displayed on install." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:73 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:76 #, no-wrap msgid "UCL" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:76 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:79 msgid "" "If the file starts with \"`[`\" then it is considered to be a UCL file. The " "UCL format is described on https://github.com/vstakhov/libucl[libucl's " "GitHub page]." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:80 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:83 msgid "" "Do not add an entry for [.filename]#pkg-message# in [.filename]#pkg-plist#." msgstr "" #. type: Title === -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:83 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:86 #, no-wrap msgid "UCL in pkg-message" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:88 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:91 msgid "" "The format is the following. It should be an array of objects. The objects " "themselves can have these keywords:" msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:89 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:92 #, no-wrap msgid "`message`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:92 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:95 msgid "The actual message to be displayed. This keyword is mandatory." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:93 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:96 #, no-wrap msgid "`type`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:95 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:98 msgid "When the message should be displayed." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:96 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:99 #, no-wrap msgid "`maximum_version`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:99 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:102 msgid "" "Only if `type` is `upgrade`. Display if upgrading from a version strictly " "lower than the version specified." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:100 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:103 #, no-wrap msgid "`minimum_version`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:103 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:106 msgid "" "Only if `type` is `upgrade`. Display if upgrading from a version strictly " "greater than the version specified." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:105 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:108 msgid "The `maximum_version` and `minimum_version` keywords can be combined." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:107 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:110 msgid "The `type` keyword can have three values:" msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:108 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:111 #, no-wrap msgid "`install`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:110 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:113 msgid "The message should only be displayed when the package is installed." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:111 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:114 #, no-wrap msgid "`remove`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:113 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:116 msgid "The message should only be displayed when the package is removed." msgstr "" #. type: Labeled list -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:114 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:117 #, no-wrap msgid "`upgrade`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:116 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:119 msgid "the message should only be displayed during an upgrade of the package.." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:121 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:124 msgid "" "To preserve the compatibility with non UCL [.filename]#pkg-message# files, " "the first line of a UCL [.filename]#pkg-message# _MUST be_ a single \"`[`\", " "and the last line _MUST be_ a single \"`]`\"." msgstr "" #. type: Block title -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:124 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:127 #, no-wrap msgid "UCL Short Strings" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:129 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:132 msgid "" "The message is delimited by double quotes `\"`, this is used for simple " "single line strings:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:137 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:140 #, no-wrap msgid "" "[\n" "{ type: install\n" " message: \"Simple message\"\n" "}\n" "]\n" msgstr "" #. type: Block title -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:142 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:145 #, no-wrap msgid "UCL Multiline Strings" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:150 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:153 msgid "" "Multiline strings use the standard here document notation. The multiline " "delimiter _must_ start just after `<<` symbols without any whitespace and it " "_must_ consist of capital letters only. To finish a multiline string, add " "the delimiter string on a line of its own without any whitespace. The " "message from <> can be written as:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:160 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:163 #, no-wrap msgid "" "[\n" "{ type: install\n" " message: < 1.0 and < 3.0 remove that file.\"\n" "}\n" "]\n" msgstr "" #. type: delimited block * 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:221 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:224 msgid "" "When displaying a message on upgrade, it is important to limit when it is " "being shown to the user. Most of the time it is by using `maximum_version` " "to limit its usage to upgrades from before a certain version when something " "specific needs to be done." msgstr "" #. type: Title == -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:226 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:229 #, no-wrap msgid "pkg-install, pkg-pre-install, and pkg-post-install" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:232 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:235 msgid "" "If the port needs to execute commands when the binary package is installed " "with `pkg add` or `pkg install`, use [.filename]#pkg-install#. It is run " "twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` " "before the package is installed, and the second time as `${SH} pkg-install " "${PKGNAME} POST-INSTALL` after it has been installed. `$2` can be tested to " "determine which mode the script is being run in. The `PKG_PREFIX` " "environment variable is set to the package installation directory." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:236 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:239 msgid "" "If using [.filename]#pkg-pre-install# or [.filename]#pkg-post-install# " "instead, the script is run only once (before or after installing the " "package), with the single argument `${PKGNAME}`. Using [.filename]#pkg-pre-" "install.lua# or [.filename]#pkg-post-install.lua# will run a lua script " "instead of a shell script. Lua scripts run by `pkg` provide some extensions " "and a few restrictions, both explained in man:pkg-lua-script[5]." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:240 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:243 msgid "" "Using [.filename]#pkg-pre-install# (or [.filename]#pkg-pre-install.lua#) and " "[.filename]#pkg-post-install# (or [.filename]#pkg-post-install.lua#) is " "preferred to using [.filename]#pkg-install#." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:243 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:270 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:246 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:273 msgid "These scripts are automatically added to the packing list." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:248 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:251 msgid "" "These scripts are here to simplify package configuration after " "installation. They _must not_ be abused to start services, stop services, " "or run any other commands that will modify the currently running system." msgstr "" #. type: Title == -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:251 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:254 #, no-wrap msgid "pkg-deinstall, pkg-pre-deinstall, and pkg-post-deinstall" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:254 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:257 msgid "These scripts execute when a package is removed." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:259 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:262 msgid "" "The [.filename]#pkg-deinstall# script is run twice by `pkg delete`. The " "first time as `${SH} pkg-deinstall ${PKGNAME} DEINSTALL` before the port is " "de-installed and the second time as `${SH} pkg-deinstall ${PKGNAME} POST-" "DEINSTALL` after the port has been de-installed. `$2` can be tested to " "determine which mode the script is being run in. The `PKG_PREFIX` " "environment variable is set to the package installation directory." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:263 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:266 msgid "" "If using [.filename]#pkg-pre-deinstall# or [.filename]#pkg-post-deinstall# " "instead, the script is run only once (before or after deinstalling the " "package), with the single argument `${PKGNAME}`. Using [.filename]#pkg-pre-" "deinstall.lua# or [.filename]#pkg-post-deinstall.lua# will run a lua script " "instead of a shell script. Lua scripts run by `pkg` provide some extensions " "and a few restrictions, both explained in man:pkg-lua-script[5]." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:267 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:270 msgid "" "Using [.filename]#pkg-pre-deinstall# (or [.filename]#pkg-pre-deinstall.lua#) " "and [.filename]#pkg-post-deinstall# (or [.filename]#pkg-post-deinstall.lua#) " "is preferred to using [.filename]#pkg-deinstall#." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:275 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:278 msgid "" "These scripts are here to simplify cleanup after package deinstallation. " "They _must not_ be abused to start services, stop services, or run any other " "commands that will modify the currently running system." msgstr "" #. type: Title == -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:278 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:281 #, no-wrap msgid "Changing the Names of pkg-*" msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:283 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:286 msgid "" "All the names of [.filename]#pkg-\\*# are defined using variables that can " "be changed in the [.filename]#Makefile# if needed. This is especially " "useful when sharing the same [.filename]#pkg-*# files among several ports or " "when it is necessary to write to one of these files. See crossref:porting-" "dads[porting-wrkdir,writing to places other than `WRKDIR`] for why it is a " "bad idea to write directly into the directory containing the [.filename]#pkg-" "*# files." msgstr "" #. type: delimited block = 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:286 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:289 msgid "" "Here is a list of variable names and their default values. (`PKGDIR` " "defaults to `${MASTERDIR}`.)" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:291 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:294 #, no-wrap msgid "Variable" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:293 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:296 #, no-wrap msgid "Default value" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:294 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:297 #, no-wrap msgid "`DESCR`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:296 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:299 #, no-wrap msgid "`${PKGDIR}/pkg-descr`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:297 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:300 #, no-wrap msgid "`PLIST`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:299 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:302 #, no-wrap msgid "`${PKGDIR}/pkg-plist`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:300 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:303 #, no-wrap msgid "`PKGINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:302 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:305 #, no-wrap msgid "`${PKGDIR}/pkg-install`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:303 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:306 #, no-wrap msgid "`PKGPREINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:305 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:308 #, no-wrap msgid "`${PKGDIR}/pkg-pre-install`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:306 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:309 #, no-wrap msgid "`PKGPOSTINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:308 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:311 #, no-wrap msgid "`${PKGDIR}/pkg-post-install`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:309 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:312 #, no-wrap msgid "`PKGDEINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:311 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:314 #, no-wrap msgid "`${PKGDIR}/pkg-deinstall`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:312 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:315 #, no-wrap msgid "`PKGPREDEINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:314 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:317 #, no-wrap msgid "`${PKGDIR}/pkg-pre-deinstall`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:315 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:318 #, no-wrap msgid "`PKGPOSTDEINSTALL`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:317 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:320 #, no-wrap msgid "`${PKGDIR}/pkg-post-deinstall`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:318 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:321 #, no-wrap msgid "`PKGMESSAGE`" msgstr "" #. type: Table -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:319 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:322 #, no-wrap msgid "`${PKGDIR}/pkg-message`" msgstr "" #. type: Title == -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:322 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:325 #, no-wrap msgid "Making Use of `SUB_FILES` and `SUB_LIST`" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:325 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:328 msgid "" "`SUB_FILES` and `SUB_LIST` are useful for dynamic values in port files, such " "as the installation `PREFIX` in [.filename]#pkg-message#." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:331 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:334 msgid "" "`SUB_FILES` specifies a list of files to be automatically modified. Each [." "filename]#file# in the `SUB_FILES` list must have a corresponding [." "filename]#file.in# present in `FILESDIR`. A modified version will be " "created as [.filename]#${WRKDIR}/file#. Files defined as a value of " "`USE_RC_SUBR` are automatically added to `SUB_FILES`. For the files [." "filename]#pkg-message#, [.filename]#pkg-install#, and [.filename]#pkg-" "deinstall#, the corresponding Makefile variable is automatically set to " "point to the processed version." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:336 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:339 msgid "" "`SUB_LIST` is a list of `VAR=VALUE` pairs. For each pair, `%%VAR%%` will be " "replaced with `VALUE` in each file listed in `SUB_FILES`. Several common " "pairs are automatically defined: `PREFIX`, `LOCALBASE`, `DATADIR`, " "`DOCSDIR`, `EXAMPLESDIR`, `WWWDIR`, and `ETCDIR`. Any line beginning with " "`@comment` followed by a space, will be deleted from resulting files after a " "variable substitution." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:338 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:341 msgid "" "This example replaces `%%ARCH%%` with the system architecture in a [." "filename]#pkg-message#:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:343 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:346 #, no-wrap msgid "" "SUB_FILES=\tpkg-message\n" "SUB_LIST=\tARCH=${ARCH}\n" msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:346 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:349 msgid "" "Note that for this example, [.filename]#pkg-message.in# must exist in " "`FILESDIR`." msgstr "" #. type: Plain text -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:348 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:351 msgid "Example of a good [.filename]#pkg-message.in#:" msgstr "" #. type: delimited block . 4 -#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:354 +#: documentation/content/en/books/porters-handbook/pkg-files/_index.adoc:357 #, no-wrap msgid "" "Now it is time to configure this package.\n" "Copy %%PREFIX%%/shared/examples/putsy/%%ARCH%%.conf into your home directory\n" "as .putsy.conf and edit it.\n" msgstr ""