FreeBSD's Google Season of Docs Idea List
Introduction
FreeBSD is an operating system used to power modern servers, desktops, and embedded platforms. A large community has continually developed it for more than thirty years. Its advanced networking, security, and storage features have made FreeBSD the platform of choice for many of the busiest web sites and most pervasive embedded networking and storage devices.
FreeBSD is currently keeping it's documentation (books, articles, FAQ, website) in the following Git repository: https://cgit.freebsd.org/doc/
The FreeBSD Documentation Project Primer is your guide to contributing to FreeBSD's docs. It contains a Quick Start section that tells you everything you need to know to get started. For further information, please contact the mentors for the task or ask on IRC FreeNode channel #bsddocs for help.
Documentation Project Idea List
Project |
Description |
Mentors |
Related material/Links |
Document formatter |
The FreeBSD has some rules about how documentation source files should be formatted (indented). Doing this manually is a tedious task and turns people away from writing documentation due to the formatting overhead compared to writing the actual content. An automatic formatter should be able to run over source files and reformat them according to our rules. The rules are outlined in the FreeBSD Documentation Project Primer and in textproc/igor. |
|
|
Update the ZFS handbook chapter |
OpenZFS is a modern filesystem with integrated volume manager that is available on FreeBSD and described in the handbook. The objective of this task is to update the handbook chapter with the current features that OpenZFS has to reflect the current state in FreeBSD. The delegated administration section needs to be expanded with examples to cover the delegation of ZFS administration to users and groups. A new section on ZFS replication (send/receive) should be written that is referencing the delegated administration section to allow unprivileged users to run ZFS replication (for backups). Boot environments (BE) should be described and how they can be used using the bectl. This should include creation of a BE, listing them, and switching to one, including a screenshot from the boot loader where they can be selected. The Tuning section should be updated and expanded with recommendations how which sysctls can be used to tune ZFS on FreeBSD. |
||
Update jails handbook chapter |
The jail chapter should be updated to reflect the current state of Jails in FreeBSD. Ressource limits and VIMAGE should be described and how to set up jails using these mechanisms. Tips and recommendations on memory and disk space use should also be added. |
|
|
Update X11 and Graphics handbook chapter |
The X11 handbook chapter should be updated to reflect the current use of FreeBSD graphics. It should describe which drivers to load for different graphics cards (legacy or modern) and how to set up a basic desktop environment using he accelerated graphics power available from these drivers. Also, changing screen resolution in the console for BIOS and UEFI should be described (screenshots welcome) to show the various capabilities of the vt console driver. |
|
|
Write a chapter on Testing in the developers handbook |
FreeBSD includes a comprehensive testing framework called kyua. Writing tests using that framework should be described in the developers handbook so that developers can write more tests. It should contain where tests are located, how to run them, and how to write a simple test case (walkthrough). |
|
|
Document configuring bsnmpd |
The bsnmpd daemon is handling SNMP on FreeBSD. Its configuration may be complex and should be explained in the FreeBSD handbook for users. The minimal common settings should be introduced in a section of the Network Servers chapter. Pros and cons (security concerns) should also be mentioned and how to use SNMP (including MIBs, receiving data from a remote system, traps, etc). |
|
|
Merge and extend the LDAP article into the handbook |
FreeBSD supports LDAP authentication and describes it in its own article. The article needs updating to reflect current LDAP server versions and clients. It should subsequently be merged into it's own handbook chapter under Network Servers chapter to show how to set up an LDAP server or connect to one using a client. A different LDAP client that is more modern should be described (setup and configuration), for example nss-pam-ldapd. |
|
|
Write missing man pages |
There is a list of missing man pages. Start writing as many man pages from that list as possible. With the help of your mentor, find the author or someone who recently changed the source file that the man page in question is about for background information and details. |
||
Add EXAMPLE sections to man pages |
The FreeBSD man pages include in many places an EXAMPLE sections, describing basic usage of the utility or command described therein. The FreeBSD wiki has a list of man pages without examples. Add as many examples to these man pages as possible in cases where it makes sense to have them. Come up with a general way of introducing the command/utility in these sections (i.e. quick start first, more advanced examples afterwards) and apply that to man pages describing similar utilities/commands. That way, the examples have a consistent approach and the reader can find things easier. |
||
Integration in Windows AD |
Write a guide how to integrate FreeBSD into an existing Windows AD domain (involves kerberos / LDAP / maybe even changes on Windows side). |
|
Maybe Linux based guides provide a starting point. |
Windows shadow copy via samba+ZFS |
Samba has a shadow copy plugin, which allows Windows users to recover old versions of files. Write a guide how to handle that with ZFS (ways of doing automatic snapshots for ZFS (ports), smb config, ). |
BenedictReuschling, Co-Mentor: AlexanderLeidinger |
Samba docs, ZFS on Linux guide, several snapshot management ports |
Integration of FreeBSD into an existing SAN |
This is about fibre channel stuff (iSCSI is already explained in the handbook)... Document which HBAs we support, and how to use / attach a LUN. |
|
|
More End-User-style HOWTOs |
add more ports related HOWTOs with a focus on end-to-end (integration of all tiers in a multi-tier setup), e.g. setup of a complete mail solution (MTA (postfix, exim, sendmail, ...), IMAP (dovecot, ...), anti-spam/av (rspamd, mailscanner, clamav, ...), DB (postgres, mysql, ...), webmail (horde, roundcube, ...), statistics), or a FreeBSD based monitoring solution (nagios, zabbix, icinga, cacti, prometheus, netdata...), or ... |
BenedictReuschling Co-Mentor: AlexanderLeidinger |
|
pNFS and NFS over TLS Howto |
Add a howto article or handbook section that explains how to setup and use parallel NFS (pNFS) and NFS over TLS. Illustrations and/or diagrams would be helpful to add, too. |
BenedictReuschling Co-Mentor: RickMacklem |