Date: Sat, 20 Mar 2021 18:03:24 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: e16d21085b - main - Fix typos, style and images paths Message-ID: <202103201803.12KI3OYA030899@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=e16d21085bebdaf6f91c49e14cff9cb960a13315 commit e16d21085bebdaf6f91c49e14cff9cb960a13315 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-03-20 17:58:59 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-03-20 18:03:12 +0000 Fix typos, style and images paths Global review of styles, typos and images paths in gjournal-desktop, releng, vinum and vm-design --- .../content/en/articles/contributing/_index.adoc | 277 ++++++-- .../content/en/articles/contributors/_index.adoc | 18 +- documentation/content/en/articles/cups/_index.adoc | 50 +- .../content/en/articles/explaining-bsd/_index.adoc | 98 ++- .../en/articles/filtering-bridges/_index.adoc | 110 ++- .../content/en/articles/fonts/_index.adoc | 143 ++-- .../en/articles/freebsd-questions/_index.adoc | 66 +- .../content/en/articles/freebsd-releng/_index.adoc | 123 +++- .../en/articles/freebsd-update-server/_index.adoc | 55 +- .../content/en/articles/geom-class/_index.adoc | 125 +++- .../en/articles/gjournal-desktop/_index.adoc | 152 +++-- documentation/content/en/articles/hubs/_index.adoc | 152 ++++- .../content/en/articles/ipsec-must/_index.adoc | 37 +- .../content/en/articles/ldap-auth/_index.adoc | 231 +++++-- .../content/en/articles/leap-seconds/_index.adoc | 30 +- .../en/articles/linux-emulation/_index.adoc | 743 +++++++++++++++++---- .../content/en/articles/linux-users/_index.adoc | 87 ++- .../en/articles/mailing-list-faq/_index.adoc | 69 +- .../content/en/articles/nanobsd/_index.adoc | 91 ++- .../content/en/articles/new-users/_index.adoc | 189 ++++-- documentation/content/en/articles/pam/_index.adoc | 204 ++++-- .../content/en/articles/pgpkeys/_index.adoc | 3 +- .../en/articles/port-mentor-guidelines/_index.adoc | 48 +- .../content/en/articles/pr-guidelines/_index.adoc | 70 +- .../en/articles/problem-reports/_index.adoc | 96 ++- .../content/en/articles/rc-scripting/_index.adoc | 399 ++++++++--- .../content/en/articles/releng/_index.adoc | 176 +++-- .../content/en/articles/remote-install/_index.adoc | 110 ++- .../content/en/articles/serial-uart/_index.adoc | 321 ++++++--- .../content/en/articles/solid-state/_index.adoc | 107 ++- .../content/en/articles/vinum/_index.adoc | 243 +++++-- .../content/en/articles/vm-design/_index.adoc | 338 ++++++++-- 32 files changed, 3732 insertions(+), 1229 deletions(-) diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index 11a6054351..16d4c1cf1a 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -30,15 +30,24 @@ This article describes the different ways in which an individual or organization toc::[] -So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. +So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the contributions of its user base to survive. +Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. -A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated. +A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. +There is always more work to be done than there are people available to do it, and more help is always appreciated. -As a volunteer, what you do is limited only by what you want to do. However, we do ask that you are aware of what other members of the FreeBSD community will expect of you. You may want to take this into account before deciding to volunteer. +As a volunteer, what you do is limited only by what you want to do. +However, we do ask that you are aware of what other members of the FreeBSD community will expect of you. +You may want to take this into account before deciding to volunteer. -The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our [.filename]#TODO# lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. People of any skill level, in almost any area, can almost certainly help the project. +The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. +As such, our [.filename]#TODO# lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. +People of any skill level, in almost any area, can almost certainly help the project. -Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. +Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. +Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. +Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. +The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. [[contrib-what]] == What Is Needed @@ -48,7 +57,9 @@ The following list of tasks and sub-projects represents something of an amalgam [[non-programmer-tasks]] === Ongoing Non-Programmer Tasks -Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. +Many people who are involved in FreeBSD are not programmers. +The Project includes documentation writers, Web designers, and support people. +All that these people need to contribute is an investment of time and a willingness to learn. . Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (Docbook is not difficult to learn, but there is no objection to ASCII submissions). . Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the link:{fdp-primer}#translations[Translations FAQ] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. @@ -57,7 +68,8 @@ Many people who are involved in FreeBSD are not programmers. The Project include [[ongoing-programmer-tasks]] === Ongoing Programmer Tasks -Most of the tasks listed here may require a considerable investment of time, an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for "weekend hackers". +Most of the tasks listed here may require a considerable investment of time, an in-depth knowledge of the FreeBSD kernel, or both. +However, there are also many useful tasks which are suitable for "weekend hackers". . If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine `current.FreeBSD.org` which builds a full release once a day-every now and again, try to install the latest release from it and report any failures in the process. . Read the {freebsd-bugs}. There may be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. @@ -72,15 +84,24 @@ Most of the tasks listed here may require a considerable investment of time, an === Work through the PR Database -The https://bugs.FreeBSD.org/search/[FreeBSD PR list] shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if anything there takes your interest. Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. Others might be much more complex, or might not even have a fix included at all. +The https://bugs.FreeBSD.org/search/[FreeBSD PR list] shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. +The PR database includes both programmer and non-programmer tasks. +Look through the open PRs, and see if anything there takes your interest. +Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. +Others might be much more complex, or might not even have a fix included at all. -Start with the PRs that have not been assigned to anyone else. If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it-they might already have a patch ready to be tested, or further ideas that you can discuss with them. +Start with the PRs that have not been assigned to anyone else. +If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it-they might already have a patch ready to be tested, or further ideas that you can discuss with them. === Ongoing Ports Tasks -The Ports Collection is a perpetual work in progress. We want to provide our users with an easy to use, up to date, high quality repository of third party software. We need people to donate some of their time and effort to help us achieve this goal. +The Ports Collection is a perpetual work in progress. +We want to provide our users with an easy to use, up to date, high quality repository of third party software. +We need people to donate some of their time and effort to help us achieve this goal. -Anyone can get involved, and there are lots of different ways to do so. Contributing to ports is an excellent way to help "give back" something to the project. Whether you are looking for an ongoing role, or a fun challenge for a rainy day, we would love to have your help! +Anyone can get involved, and there are lots of different ways to do so. +Contributing to ports is an excellent way to help "give back" something to the project. +Whether you are looking for an ongoing role, or a fun challenge for a rainy day, we would love to have your help! There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order: @@ -91,7 +112,8 @@ There are a number of easy ways you can contribute to keeping the ports tree up === Pick one of the items from the Ideas page -The https://wiki.freebsd.org/IdeasPage[FreeBSD list of projects and ideas for volunteers] is also available for people willing to contribute to the FreeBSD project. The list is being regularly updated and contains items for both programmers and non-programmers with information about each project. +The https://wiki.freebsd.org/IdeasPage[FreeBSD list of projects and ideas for volunteers] is also available for people willing to contribute to the FreeBSD project. +The list is being regularly updated and contains items for both programmers and non-programmers with information about each project. [[contrib-how]] == How to Contribute @@ -101,25 +123,39 @@ Contributions to the system generally fall into one or more of the following 5 c [[contrib-general]] === Bug Reports and General Commentary -An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. See link:{handbook}#eresources-mail[The FreeBSD Handbook] for more information about this and other mailing lists. +An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. +Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. +See link:{handbook}#eresources-mail[The FreeBSD Handbook] for more information about this and other mailing lists. -If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put `[PATCH]` in the synopsis of the report. When including patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. When patches are a lot larger than 20KB, consider compressing them (eg. with man:gzip[1] or man:bzip2[1]) prior to uploading them. +If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. +Try to fill-in each field of the bug report. +Unless they exceed 65KB, include any patches directly in the report. +If the patch is suitable to be applied to the source tree put `[PATCH]` in the synopsis of the report. +When including patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. +When patches are a lot larger than 20KB, consider compressing them (eg. with man:gzip[1] or man:bzip2[1]) prior to uploading them. -After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem. +After filing a report, you should receive confirmation along with a tracking number. +Keep this tracking number so that you can update us with details about the problem. See also link:{problem-reports}[this article] on how to write good problem reports. === Changes to the Documentation -Changes to the documentation are overseen by the {freebsd-doc}. Please look at the link:{fdp-primer}[FreeBSD Documentation Project Primer] for complete instructions. Send submissions and changes (even small ones are welcome!) using the same method as any other bug report. +Changes to the documentation are overseen by the {freebsd-doc}. +Please look at the link:{fdp-primer}[FreeBSD Documentation Project Primer] for complete instructions. +Send submissions and changes (even small ones are welcome!) using the same method as any other bug report. === Changes to Existing Source Code -An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. See link:{handbook}#current-stable[The FreeBSD Handbook] for more information about getting and using FreeBSD-CURRENT. +An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. +There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. +See link:{handbook}#current-stable[The FreeBSD Handbook] for more information about getting and using FreeBSD-CURRENT. -Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. +Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. +Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. -Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the man:diff[1] command. +Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. +This is done with the man:diff[1] command. The preferred man:diff[1] format for submitting patches is the unified output format generated by `diff -u`. @@ -139,19 +175,29 @@ would generate a set of unified diffs for the given source file or directory hie See man:diff[1] for more information. -Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report. _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including `[PATCH]` in the synopsis of the report. +Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report. +_Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. +Indicate your submission by including `[PATCH]` in the synopsis of the report. -If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a `tar` file. Archives created with man:shar[1] are also welcome. +If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a `tar` file. +Archives created with man:shar[1] are also welcome. -If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also _very busy_ and so you should only send mail to them where it is truly necessary. +If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. +The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. +Note that this group is also _very busy_ and so you should only send mail to them where it is truly necessary. -Please refer to man:intro[9] and man:style[9] for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. +Please refer to man:intro[9] and man:style[9] for some information on coding style. +We would appreciate it if you were at least aware of this information before submitting code. === New Code or Major Value-Added Packages -In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. +In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or upload them to a web or FTP site for other people to access. +If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. -When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. Copyleft licenses such as GPLv2 are sometimes permitted. The complete listing can be found on the link:https://www.FreeBSD.org/internal/software-license/[core team licensing policy] page. +When working with large amounts of code, the touchy subject of copyrights also invariably comes up. +FreeBSD prefers free software licenses such as BSD or ISC. +Copyleft licenses such as GPLv2 are sometimes permitted. +The complete listing can be found on the link:https://www.FreeBSD.org/internal/software-license/[core team licensing policy] page. === Money or Hardware @@ -160,7 +206,9 @@ We are always very happy to accept donations to further the cause of the FreeBSD [[donations]] ==== Donating Funds -The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. +The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. +As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. +Donations to a tax-exempt entity are often deductible from taxable federal income. Donations may be sent in check form to: @@ -175,11 +223,13 @@ USA The FreeBSD Foundation is also able to accept https://www.freebsdfoundation.org/donate/[online donations] through various payment options. -More information about the FreeBSD Foundation can be found in https://people.FreeBSD.org/~jdp/foundation/announcement.html[The FreeBSD Foundation -- an Introduction]. To contact the Foundation by email, write to mailto:info@FreeBSDFoundation.org[info@FreeBSDFoundation.org]. +More information about the FreeBSD Foundation can be found in https://people.FreeBSD.org/~jdp/foundation/announcement.html[The FreeBSD Foundation -- an Introduction]. +To contact the Foundation by email, write to mailto:info@FreeBSDFoundation.org[info@FreeBSDFoundation.org]. ==== Donating Hardware -The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the link:https://www.FreeBSD.org/donations/[Donations Liaison Office]. +The FreeBSD Project happily accepts donations of hardware that it can find good use for. +If you are interested in donating hardware, please contact the link:https://www.FreeBSD.org/donations/[Donations Liaison Office]. [[ports-contributing]] == Contributing to ports @@ -189,21 +239,36 @@ The FreeBSD Project happily accepts donations of hardware that it can find good ==== Choosing an unmaintained port -Taking over maintainership of ports that are unmaintained is a great way to get involved. Unmaintained ports are only updated and fixed when somebody volunteers to work on them. There are a large number of unmaintained ports. It is a good idea to start with adopting a port that you use regularly. +Taking over maintainership of ports that are unmaintained is a great way to get involved. +Unmaintained ports are only updated and fixed when somebody volunteers to work on them. +There are a large number of unmaintained ports. +It is a good idea to start with adopting a port that you use regularly. -Unmaintained ports have their `MAINTAINER` set to `ports@FreeBSD.org`. A list of unmaintained ports and their current errors and problem reports can be seen at the http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. +Unmaintained ports have their `MAINTAINER` set to `ports@FreeBSD.org`. +A list of unmaintained ports and their current errors and problem reports can be seen at the http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. -Some ports affect a large number of others due to dependencies and slave port relationships. Generally, we want people to have some experience before they maintain such ports. +Some ports affect a large number of others due to dependencies and slave port relationships. +Generally, we want people to have some experience before they maintain such ports. -You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#. (The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. +You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#. +(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. +We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. ==== How to adopt the port -First make sure you understand your <<maintain-port>>. Also read the link:{porters-handbook}[Porter's Handbook]. _Please do not commit yourself to more than you feel you can comfortably handle._ +First make sure you understand your <<maintain-port>>. +Also read the link:{porters-handbook}[Porter's Handbook]. +_Please do not commit yourself to more than you feel you can comfortably handle._ -You may request maintainership of any unmaintained port as soon as you wish. Simply set `MAINTAINER` to your own email address and send a PR (Problem Report) with the change. If the port has build errors or needs updating, you may wish to include any other changes in the same PR. This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. Submitting PRs that fix build errors or update ports are the best ways to establish one. +You may request maintainership of any unmaintained port as soon as you wish. +Simply set `MAINTAINER` to your own email address and send a PR (Problem Report) with the change. +If the port has build errors or needs updating, you may wish to include any other changes in the same PR. +This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. +Submitting PRs that fix build errors or update ports are the best ways to establish one. -File your PR with category `ports` and class `change-request`. A committer will examine your PR, commit the changes, and finally close the PR. Sometimes this process can take a little while (committers are volunteers, too :). +File your PR with category `ports` and class `change-request`. +A committer will examine your PR, commit the changes, and finally close the PR. +Sometimes this process can take a little while (committers are volunteers, too :). [[maintain-port]] === The challenge for port maintainers @@ -213,9 +278,12 @@ This section will give you an idea of why ports need to be maintained and outlin [[why-maintenance]] ==== Why ports require maintenance -Creating a port is a once-off task. Ensuring that a port is up to date and continues to build and run requires an ongoing maintenance effort. Maintainers are the people who dedicate some of their time to meeting these goals. +Creating a port is a once-off task. +Ensuring that a port is up to date and continues to build and run requires an ongoing maintenance effort. +Maintainers are the people who dedicate some of their time to meeting these goals. -The foremost reason ports need maintenance is to bring the latest and greatest in third party software to the FreeBSD community. An additional challenge is to keep individual ports working within the Ports Collection framework as it evolves. +The foremost reason ports need maintenance is to bring the latest and greatest in third party software to the FreeBSD community. +An additional challenge is to keep individual ports working within the Ports Collection framework as it evolves. As a maintainer, you will need to manage the following challenges: @@ -239,18 +307,24 @@ As a maintainer, you will need to manage the following challenges: This section outlines the process to follow to keep your ports up to date. -This is an overview. More information about upgrading a port is available in the link:{porters-handbook}[Porter's Handbook]. +This is an overview. +More information about upgrading a port is available in the link:{porters-handbook}[Porter's Handbook]. [.procedure] ==== . Watch for updates + -Monitor the upstream vendor for new versions, updates and security fixes for the software. Announcement mailing lists or news web pages are useful for doing this. Sometimes users will contact you and ask when your port will be updated. If you are busy with other things or for any reason just cannot update it at the moment, ask if they will help you by submitting an update. +Monitor the upstream vendor for new versions, updates and security fixes for the software. +Announcement mailing lists or news web pages are useful for doing this. +Sometimes users will contact you and ask when your port will be updated. +If you are busy with other things or for any reason just cannot update it at the moment, ask if they will help you by submitting an update. + -You may also receive automated email from the `FreeBSD Ports Version Check` informing you that a newer version of your port's distfile is available. More information about that system (including how to stop future emails) will be provided in the message. +You may also receive automated email from the `FreeBSD Ports Version Check` informing you that a newer version of your port's distfile is available. +More information about that system (including how to stop future emails) will be provided in the message. . Incorporate changes + -When they become available, incorporate the changes into the port. You need to be able to generate a patch between the original port and your updated port. +When they become available, incorporate the changes into the port. +You need to be able to generate a patch between the original port and your updated port. . Review and test + Thoroughly review and test your changes: @@ -263,34 +337,44 @@ Thoroughly review and test your changes: . Submit changes + -Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated one. Please refer to link:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. +Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated one. +Please refer to link:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. + [NOTE] ====== -Please do not submit a man:shar[1] archive of the entire port; instead, use man:diff[1] `-ruN`. In this way, committers can much more easily see exactly what changes are being made. The Porter's Handbook section on link:{porters-handbook}#port-upgrading[Upgrading] has more information. +Please do not submit a man:shar[1] archive of the entire port; instead, use man:diff[1] `-ruN`. +In this way, committers can much more easily see exactly what changes are being made. +The Porter's Handbook section on link:{porters-handbook}#port-upgrading[Upgrading] has more information. ====== . Wait + -At some stage a committer will deal with your PR. It may take minutes, or it may take weeks - so please be patient. +At some stage a committer will deal with your PR. +It may take minutes, or it may take weeks - so please be patient. . Give feedback + -If a committer finds a problem with your changes, they will most likely refer it back to you. A prompt response will help get your PR committed faster, and is better for maintaining a thread of conversation when trying to resolve any problems. +If a committer finds a problem with your changes, they will most likely refer it back to you. +A prompt response will help get your PR committed faster, and is better for maintaining a thread of conversation when trying to resolve any problems. . And Finally + -Your changes will be committed and your port will have been updated. The PR will then be closed by the committer. That's it! +Your changes will be committed and your port will have been updated. +The PR will then be closed by the committer. That's it! ==== ===== Ensure your ports continue to build correctly This section is about discovering and fixing problems that stop your ports from building correctly. -FreeBSD only guarantees that the Ports Collection works on the `-STABLE` branches. In theory, you should be able to get by with running the latest release of each stable branch (since the ABIs are not supposed to change) but if you can run the branch, that is even better. +FreeBSD only guarantees that the Ports Collection works on the `-STABLE` branches. +In theory, you should be able to get by with running the latest release of each stable branch (since the ABIs are not supposed to change) but if you can run the branch, that is even better. -Since the majority of FreeBSD installations run on PC-compatible machines (what is termed the `i386` architecture), we expect you to keep the port working on that architecture. We prefer that ports also work on the `amd64` architecture running native. It is completely fair to ask for help if you do not have one of these machines. +Since the majority of FreeBSD installations run on PC-compatible machines (what is termed the `i386` architecture), we expect you to keep the port working on that architecture. +We prefer that ports also work on the `amd64` architecture running native. +It is completely fair to ask for help if you do not have one of these machines. [NOTE] ==== -The usual failure modes for non-`x86` machines are that the original programmers assumed that, for instance, pointers are `int`-s, or that a relatively lax older gcc compiler was being used. More and more, application authors are reworking their code to remove these assumptions - but if the author is not actively maintaining their code, you may need to do this yourself. +The usual failure modes for non-`x86` machines are that the original programmers assumed that, for instance, pointers are `int`-s, or that a relatively lax older gcc compiler was being used. +More and more, application authors are reworking their code to remove these assumptions - but if the author is not actively maintaining their code, you may need to do this yourself. ==== These are the tasks you need to perform to ensure your port is able to be built: @@ -302,7 +386,9 @@ These are the tasks you need to perform to ensure your port is able to be built: Check your mail for mail from `pkg-fallout@FreeBSD.org` and the http://portscout.FreeBSD.org[distfiles scanner] to see if any of the port which are failing to build are out of date. . Collect information + -Once you are aware of a problem, collect information to help you fix it. Build errors reported by `pkg-fallout` are accompanied by logs which will show you where the build failed. If the failure was reported to you by a user, ask them to send you information which may help in diagnosing the problem, such as: +Once you are aware of a problem, collect information to help you fix it. +Build errors reported by `pkg-fallout` are accompanied by logs which will show you where the build failed. +If the failure was reported to you by a user, ask them to send you information which may help in diagnosing the problem, such as: ** Build logs ** The commands and options used to build the port (including options set in [.filename]#/etc/make.conf#) @@ -313,20 +399,25 @@ Once you are aware of a problem, collect information to help you fix it. Build e . Investigate and find a solution + -Unfortunately there is no straightforward process to follow to do this. Remember, though: if you are stuck, ask for help! The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful. +Unfortunately there is no straightforward process to follow to do this. +Remember, though: if you are stuck, ask for help! The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful. . Submit changes + Just as with updating a port, you should now incorporate changes, review and test, submit your changes in a PR, and provide feedback if required. . Send patches to upstream authors + -In some cases, you will have to make patches to the port to make it run on FreeBSD. Some (but not all) upstream authors will accept such patches back into their code for the next release. If so, this may even help their users on other BSD-based systems as well and perhaps save duplicated effort. Please consider sending any applicable patches to the authors as a courtesy. +In some cases, you will have to make patches to the port to make it run on FreeBSD. +Some (but not all) upstream authors will accept such patches back into their code for the next release. +If so, this may even help their users on other BSD-based systems as well and perhaps save duplicated effort. +Please consider sending any applicable patches to the authors as a courtesy. ==== ===== Investigate bug reports and PRs related to your port This section is about discovering and fixing bugs. -FreeBSD-specific bugs are generally caused by assumptions about the build and runtime environments that do not apply to FreeBSD. You are less likely to encounter a problem of this type, but it can be more subtle and difficult to diagnose. +FreeBSD-specific bugs are generally caused by assumptions about the build and runtime environments that do not apply to FreeBSD. +You are less likely to encounter a problem of this type, but it can be more subtle and difficult to diagnose. These are the tasks you need to perform to ensure your port continues to work as intended: @@ -334,16 +425,19 @@ These are the tasks you need to perform to ensure your port continues to work as ==== . Respond to bug reports + -Bugs may be reported to you through email via the https://bugs.FreeBSD.org/search/[Problem Report database]. Bugs may also be reported directly to you by users. +Bugs may be reported to you through email via the https://bugs.FreeBSD.org/search/[Problem Report database]. +Bugs may also be reported directly to you by users. + -You should respond to PRs and other reports within 14 days, but please try not to take that long. Try to respond as soon as possible, even if it is just to say you need some more time before you can work on the PR. +You should respond to PRs and other reports within 14 days, but please try not to take that long. +Try to respond as soon as possible, even if it is just to say you need some more time before you can work on the PR. + If you have not responded after 14 days, any committer may commit from a PR that you have not responded to via a `maintainer-timeout`. . Collect information + If the person reporting the bug has not also provided a fix, you need to collect the information that will allow you to generate one. + -If the bug is reproducible, you can collect most of the required information yourself. If not, ask the person who reported the bug to collect the information for you, such as: +If the bug is reproducible, you can collect most of the required information yourself. +If not, ask the person who reported the bug to collect the information for you, such as: ** A detailed description of their actions, expected program behavior and actual behavior ** Copies of input data used to trigger the bug @@ -353,28 +447,43 @@ If the bug is reproducible, you can collect most of the required information you . Eliminate incorrect reports + -Some bug reports may be incorrect. For example, the user may have simply misused the program; or their installed packages may be out of date and require updating. Sometimes a reported bug is not specific to FreeBSD. In this case report the bug to the upstream developers. If the bug is within your capabilities to fix, you can also patch the port so that the fix is applied before the next upstream release. +Some bug reports may be incorrect. +For example, the user may have simply misused the program; or their installed packages may be out of date and require updating. +Sometimes a reported bug is not specific to FreeBSD. +In this case report the bug to the upstream developers. +If the bug is within your capabilities to fix, you can also patch the port so that the fix is applied before the next upstream release. . Find a solution + -As with build errors, you will need to sort out a fix to the problem. Again, remember to ask if you are stuck! +As with build errors, you will need to sort out a fix to the problem. +Again, remember to ask if you are stuck! . Submit or approve changes + -Just as with updating a port, you should now incorporate changes, review and test, and submit your changes in a PR (or send a follow-up if a PR already exists for the problem). If another user has submitted changes in the PR, you can also send a follow-up saying whether or not you approve the changes. +Just as with updating a port, you should now incorporate changes, review and test, and submit your changes in a PR (or send a follow-up if a PR already exists for the problem). +If another user has submitted changes in the PR, you can also send a follow-up saying whether or not you approve the changes. ==== ===== Providing support -Part of being a maintainer is providing support - not for the software in general - but for the port and any FreeBSD-specific quirks and problems. Users may contact you with questions, suggestions, problems and patches. Most of the time their correspondence will be specific to FreeBSD. +Part of being a maintainer is providing support - not for the software in general - but for the port and any FreeBSD-specific quirks and problems. +Users may contact you with questions, suggestions, problems and patches. +Most of the time their correspondence will be specific to FreeBSD. -Occasionally you may have to invoke your skills in diplomacy, and kindly point users seeking general support to the appropriate resources. Less frequently you will encounter a person asking why the `RPMS` are not up to date or how can they get the software to run under Foo Linux. Take the opportunity to tell them that your port is up to date (if it is, of course!), and suggest that they try FreeBSD. +Occasionally you may have to invoke your skills in diplomacy, and kindly point users seeking general support to the appropriate resources. +Less frequently you will encounter a person asking why the `RPMS` are not up to date or how can they get the software to run under Foo Linux. +Take the opportunity to tell them that your port is up to date (if it is, of course!), and suggest that they try FreeBSD. -Sometimes users and developers will decide that you are a busy person whose time is valuable and do some of the work for you. For example, they might: +Sometimes users and developers will decide that you are a busy person whose time is valuable and do some of the work for you. +For example, they might: * submit a PR or send you patches to update your port, * investigate and perhaps provide a fix to a PR, or * otherwise submit changes to your port. -In these cases your main obligation is to respond in a timely manner. Again, the timeout for non-responsive maintainers is 14 days. After this period changes may be committed unapproved. They have taken the trouble to do this for you; so please try to at least respond promptly. Then review, approve, modify or discuss their changes with them as soon as possible. +In these cases your main obligation is to respond in a timely manner. +Again, the timeout for non-responsive maintainers is 14 days. +After this period changes may be committed unapproved. +They have taken the trouble to do this for you; so please try to at least respond promptly. +Then review, approve, modify or discuss their changes with them as soon as possible. If you can make them feel that their contribution is appreciated (and it should be) you will have a better chance persuading them to do more things for you in the future :-). @@ -383,37 +492,57 @@ If you can make them feel that their contribution is appreciated (and it should There are two really good places to find a port that needs some attention. -You can use the https://bugs.freebsd.org/search[web interface] to the Problem Report database to search through and view unresolved PRs. The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the `sw-bug` class is a good place to start). +You can use the https://bugs.freebsd.org/search[web interface] to the Problem Report database to search through and view unresolved PRs. +The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the `sw-bug` class is a good place to start). -The other place is the http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem. +The other place is the http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. +In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. +It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem. -Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. Otherwise create a new PR. Your changes will be reviewed and, if everything checks out, committed. +Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. +Otherwise create a new PR. +Your changes will be reviewed and, if everything checks out, committed. [[mortal-coil]] === When to call it quits -As your interests and commitments change, you may find that you no longer have time to continue some (or all) of your ports contributions. That is fine! Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer. In this way we can go ahead and allow other people to try to work on existing problems with the port without waiting for your response. Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it! +As your interests and commitments change, you may find that you no longer have time to continue some (or all) of your ports contributions. +That is fine! Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer. +In this way we can go ahead and allow other people to try to work on existing problems with the port without waiting for your response. +Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it! -In any case, the Ports Management Team (`portmgr`) reserves the right to reset your maintainership if you have not actively maintained your port in some time. (Currently, this is set to 3 months.) By this, we mean that there are unresolved problems or pending updates that have not been worked on during that time. +In any case, the Ports Management Team (`portmgr`) reserves the right to reset your maintainership if you have not actively maintained your port in some time. +(Currently, this is set to 3 months.) +By this, we mean that there are unresolved problems or pending updates that have not been worked on during that time. [[resources]] === Resources for ports maintainers and contributors The link:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy! -link:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR. In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs. +link:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR. +In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs. The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. -The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System] can show you cross-referenced information about ports such as build errors and problem reports. If you are a maintainer you can use it to check on the build status of your ports. As a contributor you can use it to find broken and unmaintained ports that need to be fixed. +The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System] can show you cross-referenced information about ports such as build errors and problem reports. +If you are a maintainer you can use it to check on the build status of your ports. +As a contributor you can use it to find broken and unmaintained ports that need to be fixed. -The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner] can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated. +The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner] can show you ports for which the distfiles are not fetchable. +You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated. -package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository] +package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. +Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository] -man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. portlint is a simple heuristic application, so you should use it __only as a guide__. If portlint suggests changes which seem unreasonable, consult the link:{porters-handbook}[Porter's Handbook] or ask for advice. +man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. +portlint is a simple heuristic application, so you should use it __only as a guide__. +If portlint suggests changes which seem unreasonable, consult the link:{porters-handbook}[Porter's Handbook] or ask for advice. -The {freebsd-ports} is for general ports-related discussion. It is a good place to ask for help. You can https://lists.freebsd.org/mailman/listinfo[subscribe, or read and search the list archives]. Reading the archives of the {freebsd-ports-bugs} and the {svn-ports-head} may also be of interest. +The {freebsd-ports} is for general ports-related discussion. +It is a good place to ask for help. +You can https://lists.freebsd.org/mailman/listinfo[subscribe, or read and search the list archives]. +Reading the archives of the {freebsd-ports-bugs} and the {svn-ports-head} may also be of interest. [[ideas-contributing]] == Getting Started in Other Areas diff --git a/documentation/content/en/articles/contributors/_index.adoc b/documentation/content/en/articles/contributors/_index.adoc index 39a95f542e..1919f846c6 100644 --- a/documentation/content/en/articles/contributors/_index.adoc +++ b/documentation/content/en/articles/contributors/_index.adoc @@ -96,7 +96,8 @@ The following individuals and businesses have generously contributed hardware fo [[staff-committers]] == The FreeBSD Developers -These are the people who have commit privileges and do the engineering work on the FreeBSD source tree. All core team members are also developers. +These are the people who have commit privileges and do the engineering work on the FreeBSD source tree. +All core team members are also developers. (in alphabetical order by last name): @@ -105,7 +106,8 @@ include::content/en/articles/contributors/contrib-committers.adoc[] [[contrib-corealumni]] == Core Team Alumni -The following people were members of the FreeBSD core team during the periods indicated. We thank them for their past efforts in the service of the FreeBSD project. +The following people were members of the FreeBSD core team during the periods indicated. +We thank them for their past efforts in the service of the FreeBSD project. _In rough reverse chronological order:_ @@ -114,7 +116,8 @@ include::content/en/articles/contributors/contrib-corealumni.adoc[] [[contrib-develalumni]] == Development Team Alumni -The following people were members of the FreeBSD development team during the periods indicated. We thank them for their past efforts in the service of the FreeBSD project. +The following people were members of the FreeBSD development team during the periods indicated. +We thank them for their past efforts in the service of the FreeBSD project. _In rough reverse chronological order:_ @@ -123,7 +126,8 @@ include::content/en/articles/contributors/contrib-develalumni.adoc[] [[contrib-portmgralumni]] == Ports Management Team Alumni -The following people were members of the FreeBSD portmgr team during the periods indicated. We thank them for their past efforts in the service of the FreeBSD project. +The following people were members of the FreeBSD portmgr team during the periods indicated. +We thank them for their past efforts in the service of the FreeBSD project. _In rough reverse chronological order:_ @@ -132,7 +136,8 @@ include::content/en/articles/contributors/contrib-portmgralumni.adoc[] [[contrib-develinmemoriam]] == Development Team: In Memoriam -During the many years that the FreeBSD Project has been in existence, sadly, some of our developers have passed away. Here are some remembrances. +During the many years that the FreeBSD Project has been in existence, sadly, some of our developers have passed away. +Here are some remembrances. _In rough reverse chronological order of their passing:_ @@ -141,7 +146,8 @@ include::content/en/articles/contributors/contrib-develinmemoriam.adoc[] [[contrib-derived]] == Derived Software Contributors -This software was originally derived from William F. Jolitz's 386BSD release 0.1, though almost none of the original 386BSD specific code remains. This software has been essentially re-implemented from the 4.4BSD-Lite release provided by the Computer Science Research Group (CSRG) at the University of California, Berkeley and associated academic contributors. +This software was originally derived from William F. Jolitz's 386BSD release 0.1, though almost none of the original 386BSD specific code remains. +This software has been essentially re-implemented from the 4.4BSD-Lite release provided by the Computer Science Research Group (CSRG) at the University of California, Berkeley and associated academic contributors. There are also portions of NetBSD and OpenBSD that have been integrated into FreeBSD as well, and we would therefore like to thank all the contributors to NetBSD and OpenBSD for their work. diff --git a/documentation/content/en/articles/cups/_index.adoc b/documentation/content/en/articles/cups/_index.adoc index c617d871ce..008369f0ad 100644 --- a/documentation/content/en/articles/cups/_index.adoc +++ b/documentation/content/en/articles/cups/_index.adoc @@ -29,9 +29,13 @@ toc::[] [[printing-cups]] == An Introduction to the Common Unix Printing System (CUPS) -CUPS, the Common UNIX Printing System, provides a portable printing layer for UNIX(R)-based operating systems. It has been developed by Easy Software Products to promote a standard printing solution for all UNIX(R) vendors and users. +CUPS, the Common UNIX Printing System, provides a portable printing layer for UNIX(R)-based operating systems. +It has been developed by Easy Software Products to promote a standard printing solution for all UNIX(R) vendors and users. -CUPS uses the Internet Printing Protocol (IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD), Server Message Block (SMB), and AppSocket (aka JetDirect) protocols are also supported with reduced functionality. CUPS adds network printer browsing and PostScript Printer Description (PPD) based printing options to support real-world printing under UNIX(R). As a result, CUPS is ideally-suited for sharing and accessing printers in mixed environments of FreeBSD, Linux(R), Mac OS(R) X, or Windows(R). +CUPS uses the Internet Printing Protocol (IPP) as the basis for managing print jobs and queues. +The Line Printer Daemon (LPD), Server Message Block (SMB), and AppSocket (aka JetDirect) protocols are also supported with reduced functionality. +CUPS adds network printer browsing and PostScript Printer Description (PPD) based printing options to support real-world printing under UNIX(R). +As a result, CUPS is ideally-suited for sharing and accessing printers in mixed environments of FreeBSD, Linux(R), Mac OS(R) X, or Windows(R). The main site for CUPS is http://www.cups.org/[http://www.cups.org/]. @@ -45,12 +49,14 @@ To install CUPS using a precompiled binary, issue the following command from a r # pkg install cups .... -Other optional, but recommended, packages are package:print/gutenprint[] and package:print/hplip[], both of which add drivers and utilities for a variety of printers. Once installed, the CUPS configuration files can be found in the directory [.filename]#/usr/local/etc/cups#. +Other optional, but recommended, packages are package:print/gutenprint[] and package:print/hplip[], both of which add drivers and utilities for a variety of printers. +Once installed, the CUPS configuration files can be found in the directory [.filename]#/usr/local/etc/cups#. [[printing-cups-configuring-server]] == Configuring the CUPS Print Server -After installation, a few files must be edited in order to configure the CUPS server. First, create or modify, as the case may be, the file [.filename]#/etc/devfs.rules# and add the following information to set the proper permissions on all potential printer devices and to associate printers with the `cups` user group: +After installation, a few files must be edited in order to configure the CUPS server. +First, create or modify, as the case may be, the file [.filename]#/etc/devfs.rules# and add the following information to set the proper permissions on all potential printer devices and to associate printers with the `cups` user group: [.programlisting] .... @@ -63,7 +69,8 @@ add path 'usb/X.Y.Z' mode 0660 group cups [NOTE] ==== -Note that _X_, _Y_, and _Z_ should be replaced with the target USB device listed in the [.filename]#/dev/usb# directory that corresponds to the printer. To find the correct device, examine the output of man:dmesg[8], where [.filename]#ugenX.Y# lists the printer device, which is a symbolic link to a USB device in [.filename]#/dev/usb#. +Note that _X_, _Y_, and _Z_ should be replaced with the target USB device listed in the [.filename]#/dev/usb# directory that corresponds to the printer. +To find the correct device, examine the output of man:dmesg[8], where [.filename]#ugenX.Y# lists the printer device, which is a symbolic link to a USB device in [.filename]#/dev/usb#. ==== Next, add two lines to [.filename]#/etc/rc.conf# as follows: @@ -94,21 +101,31 @@ Once these changes have been made, the man:devfs[8] and CUPS systems must both b [[printing-cups-configuring-printers]] == Configuring Printers on the CUPS Print Server -After the CUPS system has been installed and configured, the administrator can begin configuring the local printers attached to the CUPS print server. This part of the process is very similar, if not identical, to configuring CUPS printers on other UNIX(R)-based operating systems, such as a Linux(R) distribution. +After the CUPS system has been installed and configured, the administrator can begin configuring the local printers attached to the CUPS print server. +This part of the process is very similar, if not identical, to configuring CUPS printers on other UNIX(R)-based operating systems, such as a Linux(R) distribution. -The primary means for managing and administering the CUPS server is through the web-based interface, which can be found by launching a web browser and entering http://localhost:631[http://localhost:631] in the browser's URL bar. If the CUPS server is on another machine on the network, substitute the server's local IP address for `localhost`. The CUPS web interface is fairly self-explanatory, as there are sections for managing printers and print jobs, authorizing users, and more. Additionally, on the right-hand side of the Administration screen are several check-boxes allowing easy access to commonly-changed settings, such as whether to share published printers connected to the system, whether to allow remote administration of the CUPS server, and whether to allow users additional access and privileges to the printers and print jobs. +The primary means for managing and administering the CUPS server is through the web-based interface, which can be found by launching a web browser and entering http://localhost:631[http://localhost:631] in the browser's URL bar. +If the CUPS server is on another machine on the network, substitute the server's local IP address for `localhost`. +The CUPS web interface is fairly self-explanatory, as there are sections for managing printers and print jobs, authorizing users, and more. +Additionally, on the right-hand side of the Administration screen are several check-boxes allowing easy access to commonly-changed settings, such as whether to share published printers connected to the system, whether to allow remote administration of the CUPS server, and whether to allow users additional access and privileges to the printers and print jobs. -Adding a printer is generally as easy as clicking "Add Printer" at the Administration screen of the CUPS web interface, or clicking one of the "New Printers Found" buttons also at the Administration screen. When presented with the "Device" drop-down box, simply select the desired locally-attached printer, and then continue through the process. If one has added the package:print/gutenprint-cups[] or package:print/hplip[] ports or packages as referenced above, then additional print drivers will be available in the subsequent screens that might provide more stability or features. +Adding a printer is generally as easy as clicking "Add Printer" at the Administration screen of the CUPS web interface, or clicking one of the "New Printers Found" buttons also at the Administration screen. +When presented with the "Device" drop-down box, simply select the desired locally-attached printer, and then continue through the process. +If one has added the package:print/gutenprint-cups[] or package:print/hplip[] ports or packages as referenced above, then additional print drivers will be available in the subsequent screens that might provide more stability or features. [[printing-cups-clients]] == Configuring CUPS Clients -Once the CUPS server has been configured and printers have been added and published to the network, the next step is to configure the clients, or the machines that are going to access the CUPS server. If one has a single desktop machine that is acting as both server and client, then much of this information may not be needed. +Once the CUPS server has been configured and printers have been added and published to the network, the next step is to configure the clients, or the machines that are going to access the CUPS server. +If one has a single desktop machine that is acting as both server and client, then much of this information may not be needed. [[printing-cups-clients-unix]] === UNIX(R) Clients -CUPS will also need to be installed on your UNIX(R) clients. Once CUPS is installed on the clients, then CUPS printers that are shared across the network are often automatically discovered by the printer managers for various desktop environments such as GNOME or KDE. Alternatively, one can access the local CUPS interface on the client machine at http://localhost:631[http://localhost:631] and click on "Add Printer" in the Administration section. When presented with the "Device" drop-down box, simply select the networked CUPS printer, if it was automatically discovered, or select `ipp` or `http` and enter the IPP or HTTP URI of the networked CUPS printer, usually in one of the two following syntaxes: +CUPS will also need to be installed on your UNIX(R) clients. +Once CUPS is installed on the clients, then CUPS printers that are shared across the network are often automatically discovered by the printer managers for various desktop environments such as GNOME or KDE. +Alternatively, one can access the local CUPS interface on the client machine at http://localhost:631[http://localhost:631] and click on "Add Printer" in the Administration section. +When presented with the "Device" drop-down box, simply select the networked CUPS printer, if it was automatically discovered, or select `ipp` or `http` and enter the IPP or HTTP URI of the networked CUPS printer, usually in one of the two following syntaxes: [.programlisting] .... @@ -132,7 +149,10 @@ In this case, _server-ip_ would be replaced by the local IP address of the CUPS [[printing-cups-clients-windows]] === Windows(R) Clients -Versions of Windows(R) prior to XP did not have the capability to natively network with IPP-based printers. However, Windows(R) XP and later versions do have this capability. Therefore, to add a CUPS printer in these versions of Windows(R) is quite easy. Generally, the Windows(R) administrator will run the Windows(R) `Add Printer` wizard, select `Network Printer` and then enter the URI in the following syntax: +Versions of Windows(R) prior to XP did not have the capability to natively network with IPP-based printers. +However, Windows(R) XP and later versions do have this capability. +Therefore, to add a CUPS printer in these versions of Windows(R) is quite easy. +Generally, the Windows(R) administrator will run the Windows(R) `Add Printer` wizard, select `Network Printer` and then enter the URI in the following syntax: [.programlisting] .... @@ -144,7 +164,13 @@ If one has an older version of Windows(R) without native IPP printing support, t [[printing-cups-troubleshooting]] == CUPS Troubleshooting -Difficulties with CUPS often lies in permissions. First, double check the man:devfs[8] permissions as outlined above. Next, check the actual permissions of the devices created in the file system. It is also helpful to make sure your user is a member of the `cups` group. If the permissions check boxes in the Administration section of the CUPS web interface do not seem to be working, another fix might be to manually backup the main CUPS configuration file located at [.filename]#/usr/local/etc/cups/cupsd.conf# and edit the various configuration options and try different combinations of configuration options. One sample [.filename]#/usr/local/etc/cups/cupsd.conf# to test is listed below. Please note that this sample [.filename]#cupsd.conf# sacrifices security for easier configuration; once the administrator successfully connects to the CUPS server and configures the clients, it is advisable to revisit this configuration file and begin locking down access. +Difficulties with CUPS often lies in permissions. +First, double check the man:devfs[8] permissions as outlined above. +Next, check the actual permissions of the devices created in the file system. +It is also helpful to make sure your user is a member of the `cups` group. +If the permissions check boxes in the Administration section of the CUPS web interface do not seem to be working, another fix might be to manually backup the main CUPS configuration file located at [.filename]#/usr/local/etc/cups/cupsd.conf# and edit the various configuration options and try different combinations of configuration options. +One sample [.filename]#/usr/local/etc/cups/cupsd.conf# to test is listed below. +Please note that this sample [.filename]#cupsd.conf# sacrifices security for easier configuration; once the administrator successfully connects to the CUPS server and configures the clients, it is advisable to revisit this configuration file and begin locking down access. [.programlisting] .... diff --git a/documentation/content/en/articles/explaining-bsd/_index.adoc b/documentation/content/en/articles/explaining-bsd/_index.adoc index 1f76b113e1..ce636eb968 100644 --- a/documentation/content/en/articles/explaining-bsd/_index.adoc +++ b/documentation/content/en/articles/explaining-bsd/_index.adoc @@ -33,7 +33,11 @@ toc::[] [[what-is-bsd]] == What is BSD? -BSD stands for "Berkeley Software Distribution". It is the name of distributions of source code from the University of California, Berkeley, which were originally extensions to AT&T's Research UNIX(R) operating system. Several open source operating system projects are based on a release of this source code known as 4.4BSD-Lite. In addition, they comprise a number of packages from other Open Source projects, including notably the GNU project. The overall operating system comprises: +BSD stands for "Berkeley Software Distribution". +It is the name of distributions of source code from the University of California, Berkeley, which were originally extensions to AT&T's Research UNIX(R) operating system. +Several open source operating system projects are based on a release of this source code known as 4.4BSD-Lite. +In addition, they comprise a number of packages from other Open Source projects, including notably the GNU project. +The overall operating system comprises: * The BSD kernel, which handles process scheduling, memory management, symmetric multi-processing (SMP), device drivers, etc. * The C library, the base API for the system. @@ -44,23 +48,44 @@ __The BSD C library is based on code from Berkeley, not the GNU project.__ __Some of the utilities are derived from the GNU project, others are not.__ * The X Window system, which handles graphical display. + -The X Window system used in most versions of BSD is maintained by the http://www.X.org/[X.Org project]. FreeBSD allows the user to choose from a variety of desktop environments, such as Gnome, KDE, or Xfce; and lightweight window managers like Openbox, Fluxbox, or Awesome. +The X Window system used in most versions of BSD is maintained by the http://www.X.org/[X.Org project]. +FreeBSD allows the user to choose from a variety of desktop environments, such as Gnome, KDE, or Xfce; and lightweight window managers like Openbox, Fluxbox, or Awesome. * Many other programs and utilities. [[what-a-real-unix]] == What, a real UNIX(R)? -The BSD operating systems are not clones, but open source derivatives of AT&T's Research UNIX(R) operating system, which is also the ancestor of the modern UNIX(R) System V. This may surprise you. How could that happen when AT&T has never released its code as open source? +The BSD operating systems are not clones, but open source derivatives of AT&T's Research UNIX(R) operating system, which is also the ancestor of the modern UNIX(R) System V. +This may surprise you. +How could that happen when AT&T has never released its code as open source? It is true that AT&T UNIX(R) is not open source, and in a copyright sense BSD is very definitely _not_ UNIX(R), but on the other hand, AT&T has imported sources from other projects, noticeably the Computer Sciences Research Group (CSRG) of the University of California in Berkeley, CA. Starting in 1976, the CSRG started releasing tapes of their software, calling them _Berkeley Software Distribution_ or __BSD__. -Initial BSD releases consisted mainly of user programs, but that changed dramatically when the CSRG landed a contract with the Defense Advanced Research Projects Agency (DARPA) to upgrade the communications protocols on their network, ARPANET. The new protocols were known as the __Internet Protocols__, later _TCP/IP_ after the most important protocols. The first widely distributed implementation was part of 4.2BSD, in 1982. - -In the course of the 1980s, a number of new workstation companies sprang up. Many preferred to license UNIX(R) rather than developing operating systems for themselves. In particular, Sun Microsystems licensed UNIX(R) and implemented a version of 4.2BSD, which they called SunOS(TM). When AT&T themselves were allowed to sell UNIX(R) commercially, they started with a somewhat bare-bones implementation called System III, to be quickly followed by System V. The System V code base did not include networking, so all implementations included additional software from the BSD, including the TCP/IP software, but also utilities such as the _csh_ shell and the _vi_ editor. Collectively, these enhancements were known as the __Berkeley Extensions__. - -The BSD tapes contained AT&T source code and thus required a UNIX(R) source license. By 1990, the CSRG's funding was running out, and it faced closure. Some members of the group decided to release the BSD code, which was Open Source, without the AT&T proprietary code. This finally happened with the __Networking Tape 2__, usually known as __Net/2__. Net/2 was not a complete operating system: about 20% of the kernel code was missing. One of the CSRG members, William F. Jolitz, wrote the remaining code and released it in early 1992 as __386BSD__. At the same time, another group of ex-CSRG members formed a commercial company called http://www.bsdi.com/[Berkeley Software Design Inc.] and released a beta version of an operating system called http://www.bsdi.com/[BSD/386], which was based on the same sources. The name of the operating system was later changed to BSD/OS. - -386BSD never became a stable operating system. Instead, two other projects split off from it in 1993: http://www.NetBSD.org/[NetBSD] and link:https://www.FreeBSD.org/[FreeBSD]. The two projects originally diverged due to differences in patience waiting for improvements to 386BSD: the NetBSD people started early in the year, and the first version of FreeBSD was not ready until the end of the year. In the meantime, the code base had diverged sufficiently to make it difficult to merge. In addition, the projects had different aims, as we will see below. In 1996, http://www.OpenBSD.org/[OpenBSD] split off from NetBSD, and in 2003, http://www.dragonflybsd.org/[DragonFlyBSD] split off from FreeBSD. +Initial BSD releases consisted mainly of user programs, but that changed dramatically when the CSRG landed a contract with the Defense Advanced Research Projects Agency (DARPA) to upgrade the communications protocols on their network, ARPANET. +The new protocols were known as the __Internet Protocols__, later _TCP/IP_ after the most important protocols. +The first widely distributed implementation was part of 4.2BSD, in 1982. + +In the course of the 1980s, a number of new workstation companies sprang up. +Many preferred to license UNIX(R) rather than developing operating systems for themselves. +In particular, Sun Microsystems licensed UNIX(R) and implemented a version of 4.2BSD, which they called SunOS(TM). +When AT&T themselves were allowed to sell UNIX(R) commercially, they started with a somewhat bare-bones implementation called System III, to be quickly followed by System V. +The System V code base did not include networking, so all implementations included additional software from the BSD, including the TCP/IP software, but also utilities such as the _csh_ shell and the _vi_ editor. +Collectively, these enhancements were known as the __Berkeley Extensions__. + +The BSD tapes contained AT&T source code and thus required a UNIX(R) source license. +By 1990, the CSRG's funding was running out, and it faced closure. +Some members of the group decided to release the BSD code, which was Open Source, without the AT&T proprietary code. +This finally happened with the __Networking Tape 2__, usually known as __Net/2__. +Net/2 was not a complete operating system: about 20% of the kernel code was missing. +One of the CSRG members, William F. Jolitz, wrote the remaining code and released it in early 1992 as __386BSD__. +At the same time, another group of ex-CSRG members formed a commercial company called http://www.bsdi.com/[Berkeley Software Design Inc.] and released a beta version of an operating system called http://www.bsdi.com/[BSD/386], which was based on the same sources. +The name of the operating system was later changed to BSD/OS. + +386BSD never became a stable operating system. +Instead, two other projects split off from it in 1993: http://www.NetBSD.org/[NetBSD] and link:https://www.FreeBSD.org/[FreeBSD]. +The two projects originally diverged due to differences in patience waiting for improvements to 386BSD: the NetBSD people started early in the year, and the first version of FreeBSD was not ready until the end of the year. +In the meantime, the code base had diverged sufficiently to make it difficult to merge. +In addition, the projects had different aims, as we will see below. In 1996, http://www.OpenBSD.org/[OpenBSD] split off from NetBSD, and in 2003, http://www.dragonflybsd.org/[DragonFlyBSD] split off from FreeBSD. [[why-is-bsd-not-better-known]] == Why is BSD not better known? @@ -71,27 +96,42 @@ For a number of reasons, BSD is relatively unknown: . Much of Linux's popularity is due to factors external to the Linux projects, such as the press, and to companies formed to provide Linux services. Until recently, the open source BSDs had no such proponents. . In 1992, AT&T sued http://www.bsdi.com/[BSDI], the vendor of BSD/386, alleging that the product contained AT&T-copyrighted code. The case was settled out of court in 1994, but the spectre of the litigation continues to haunt people. In March 2000 an article published on the web claimed that the court case had been "recently settled". + -One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was known as "BSD UNIX(R)". With the elimination of the last vestige of AT&T code from BSD, it also lost the right to the name UNIX(R). Thus you will see references in book titles to "the 4.3BSD UNIX(R) operating system" and "the 4.4BSD operating system". +One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was known as "BSD UNIX(R)". +With the elimination of the last vestige of AT&T code from BSD, it also lost the right to the name UNIX(R). +Thus you will see references in book titles to "the 4.3BSD UNIX(R) operating system" and "the 4.4BSD operating system". [[comparing-bsd-and-linux]] == Comparing BSD and Linux -So what is really the difference between, say, Debian Linux and FreeBSD? For the average user, the difference is surprisingly small: Both are UNIX(R) like operating systems. Both are developed by non-commercial projects (this does not apply to many other Linux distributions, of course). In the following section, we will look at BSD and compare it to Linux. The description applies most closely to FreeBSD, which accounts for an estimated 80% of the BSD installations, but the differences from NetBSD, OpenBSD and DragonFlyBSD are small. +So what is really the difference between, say, Debian Linux and FreeBSD? For the average user, the difference is surprisingly small: Both are UNIX(R) like operating systems. +Both are developed by non-commercial projects (this does not apply to many other Linux distributions, of course). +In the following section, we will look at BSD and compare it to Linux. +The description applies most closely to FreeBSD, which accounts for an estimated 80% of the BSD installations, but the differences from NetBSD, OpenBSD and DragonFlyBSD are small. === Who owns BSD? -No one person or corporation owns BSD. It is created and distributed by a community of highly technical and committed contributors all over the world. Some of the components of BSD are Open Source projects in their own right and managed by different project maintainers. +No one person or corporation owns BSD. +It is created and distributed by a community of highly technical and committed contributors all over the world. +Some of the components of BSD are Open Source projects in their own right and managed by different project maintainers. === How is BSD developed and updated? -The BSD kernels are developed and updated following the Open Source development model. Each project maintains a publicly accessible _source tree_ which contains all source files for the project, including documentation and other incidental files. Users can obtain a complete copy of any version. +The BSD kernels are developed and updated following the Open Source development model. +Each project maintains a publicly accessible _source tree_ which contains all source files for the project, including documentation and other incidental files. +Users can obtain a complete copy of any version. -A large number of developers worldwide contribute to improvements to BSD. They are divided into three kinds: +A large number of developers worldwide contribute to improvements to BSD. +They are divided into three kinds: * _Contributors_ write code or documentation. They are not permitted to commit (add code) directly to the source tree. In order for their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a __committer__. * _Committers_ are developers with write access to the source tree. In order to become a committer, an individual must show ability in the area in which they are active. + -It is at the individual committer's discretion whether they should obtain authority before committing changes to the source tree. In general, an experienced committer may make changes which are obviously correct without obtaining consensus. For example, a documentation project committer may correct typographical or grammatical errors without review. On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them. In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as _backing out_. All committers receive mail describing each individual commit, so it is not possible to commit secretly. +It is at the individual committer's discretion whether they should obtain authority before committing changes to the source tree. +In general, an experienced committer may make changes which are obviously correct without obtaining consensus. +For example, a documentation project committer may correct typographical or grammatical errors without review. +On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them +In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as _backing out_. +All committers receive mail describing each individual commit, so it is not possible to commit secretly. * The _Core team_. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer in order to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. This arrangement differs from Linux in a number of ways: @@ -103,13 +143,20 @@ This arrangement differs from Linux in a number of ways: === BSD releases -FreeBSD, NetBSD and OpenBSD provide the system in three different "releases". As with Linux, releases are assigned a number such as 1.4.1 or 3.5. In addition, the version number has a suffix indicating its purpose: +FreeBSD, NetBSD and OpenBSD provide the system in three different "releases". +As with Linux, releases are assigned a number such as 1.4.1 or 3.5. +In addition, the version number has a suffix indicating its purpose: . The development version of the system is called _CURRENT_. FreeBSD assigns a number to CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly different naming scheme and appends a single-letter suffix which indicates changes in the internal interfaces, for example NetBSD 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). All new development on the system goes into this branch. . At regular intervals, between two and four times a year, the projects bring out a _RELEASE_ version of the system, which is available on CD-ROM and for free download from FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. The RELEASE version is intended for end users and is the normal version of the system. NetBSD also provides _patch releases_ with a third digit, for example NetBSD 1.4.2. . As bugs are found in a RELEASE version, they are fixed, and the fixes are added to the SVN tree. In FreeBSD, the resultant version is called the _STABLE_ version, while in NetBSD and OpenBSD it continues to be called the RELEASE version. Smaller new features can also be added to this branch after a period of test in the CURRENT branch. Security and other important bug fixes are also applied to all supported RELEASE versions. -_By contrast, Linux maintains two separate code trees: the stable version and the development version. Stable versions have an even minor version number, such as 2.0, 2.2 or 2.4. Development versions have an odd minor version number, such as 2.1, 2.3 or 2.5. In each case, the number is followed by a further number designating the exact release. In addition, each vendor adds their own userland programs and utilities, so the name of the distribution is also important. Each distribution vendor also assigns version numbers to the distribution, so a complete description might be something like "TurboLinux 6.0 with kernel 2.2.14"_ +_By contrast, Linux maintains two separate code trees: the stable version and the development version. +Stable versions have an even minor version number, such as 2.0, 2.2 or 2.4. +Development versions have an odd minor version number, such as 2.1, 2.3 or 2.5. +In each case, the number is followed by a further number designating the exact release. +In addition, each vendor adds their own userland programs and utilities, so the name of the distribution is also important. +Each distribution vendor also assigns version numbers to the distribution, so a complete description might be something like "TurboLinux 6.0 with kernel 2.2.14"_ === What versions of BSD are available? @@ -129,19 +176,26 @@ There are also two additional BSD UNIX(R) operating systems which are not open s === How does the BSD license differ from the GNU Public license? -Linux is available under the http://www.fsf.org/copyleft/gpl.html[GNU General Public License] (GPL), which is designed to eliminate closed source software. In particular, any derivative work of a product released under the GPL must also be supplied with source code if requested. By contrast, the http://www.opensource.org/licenses/bsd-license.html[BSD license] is less restrictive: binary-only distributions are allowed. This is particularly attractive for embedded applications. +Linux is available under the http://www.fsf.org/copyleft/gpl.html[GNU General Public License] (GPL), which is designed to eliminate closed source software. +In particular, any derivative work of a product released under the GPL must also be supplied with source code if requested. +By contrast, the http://www.opensource.org/licenses/bsd-license.html[BSD license] is less restrictive: binary-only distributions are allowed. +This is particularly attractive for embedded applications. === What else should I know? -Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. +Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. +The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. +There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. -The "all from one supplier" nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. BSD handles library version upgrades by providing compatibility modules for earlier library versions, so it is possible to run binaries which are several years old with no problems. +The "all from one supplier" nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. +BSD handles library version upgrades by providing compatibility modules for earlier library versions, so it is possible to run binaries which are several years old with no problems. === Which should I use, BSD or Linux? What does this all mean in practice? Who should use BSD, who should use Linux? -This is a very difficult question to answer. Here are some guidelines: +This is a very difficult question to answer. +Here are some guidelines: * "If it ain't broke, don't fix it": If you already use an open source operating system, and you are happy with it, there is probably no good reason to change. * BSD systems, in particular FreeBSD, can have notably higher performance than Linux. But this is not across the board. In many cases, there is little or no difference in performance. In some cases, Linux may perform better than FreeBSD. diff --git a/documentation/content/en/articles/filtering-bridges/_index.adoc b/documentation/content/en/articles/filtering-bridges/_index.adoc index a98bc5e6f1..d880fb95f6 100644 --- a/documentation/content/en/articles/filtering-bridges/_index.adoc +++ b/documentation/content/en/articles/filtering-bridges/_index.adoc @@ -22,9 +22,12 @@ include::shared/en/urls.adoc[] [.abstract-title] Abstract -Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. The device that connects the two networks in this way is called a bridge. A FreeBSD system with two network interfaces is enough in order to act as a bridge. +Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. +The device that connects the two networks in this way is called a bridge. +A FreeBSD system with two network interfaces is enough in order to act as a bridge. -A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports. +A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. +Under many points of view a bridge is similar to an Ethernet switch with only two ports. ''' @@ -33,26 +36,35 @@ toc::[] [[filtering-bridges-why]] == Why use a filtering bridge? -More and more frequently, thanks to the lowering costs of broad band Internet connections (xDSL) and also because of the reduction of available IPv4 addresses, many companies are connected to the Internet 24 hours on 24 and with few (sometimes not even a power of 2) IP addresses. In these situations it is often desirable to have a firewall that filters incoming and outgoing traffic from and towards Internet, but a packet filtering solution based on router may not be applicable, either due to subnetting issues, the router is owned by the connectivity supplier (ISP), or because it does not support such functionalities. In these scenarios the use of a filtering bridge is highly advised. +More and more frequently, thanks to the lowering costs of broad band Internet connections (xDSL) and also because of the reduction of available IPv4 addresses, many companies are connected to the Internet 24 hours on 24 and with few (sometimes not even a power of 2) IP addresses. +In these situations it is often desirable to have a firewall that filters incoming and outgoing traffic from and towards Internet, but a packet filtering solution based on router may not be applicable, either due to subnetting issues, the router is owned by the connectivity supplier (ISP), or because it does not support such functionalities. +In these scenarios the use of a filtering bridge is highly advised. A bridge-based firewall can be configured and inserted between the xDSL router and your Ethernet hub/switch without any IP numbering issues. [[filtering-bridges-how]] == How to Install -Adding bridge functionalities to a FreeBSD system is not difficult. Since 4.5 release it is possible to load such functionalities as modules instead of having to rebuild the kernel, simplifying the procedure a great deal. In the following subsections I will explain both installation ways. +Adding bridge functionalities to a FreeBSD system is not difficult. +Since 4.5 release it is possible to load such functionalities as modules instead of having to rebuild the kernel, simplifying the procedure a great deal. +In the following subsections I will explain both installation ways. [IMPORTANT] ==== -_Do not_ follow both instructions: a procedure _excludes_ the other one. Select the best choice according to your needs and abilities. +_Do not_ follow both instructions: a procedure _excludes_ the other one. +Select the best choice according to your needs and abilities. ==== -Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. Moreover, to have a good throughput, the cards should be PCI bus mastering cards. The best choices are still the Intel EtherExpress(TM) Pro, followed by the 3Com(R) 3c9xx series. To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. +Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. +Moreover, to have a good throughput, the cards should be PCI bus mastering cards. +The best choices are still the Intel EtherExpress(TM) Pro, followed by the 3Com(R) 3c9xx series. +To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. [[filtering-bridges-kernel]] === Kernel Configuration -So you have decided to use the older but well tested installation method. To begin, you have to add the following rows to your kernel configuration file: +So you have decided to use the older but well tested installation method. +To begin, you have to add the following rows to your kernel configuration file: [.programlisting] .... @@ -63,7 +75,8 @@ options IPFIREWALL_VERBOSE *** 8945 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202103201803.12KI3OYA030899>