This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- The FreeBSD Project
- Technical writer:
- Larry
- Project name:
- Updates to FreeBSD handbooks
- Project length:
- Long running (5 months)
Project description
This GSoD2020 project will consist of two chapters in the FreeBSD handbooks:
- Testing: New chapter in the FreeBSD Developers' Handbook
- LDAP: Updated article merged into chapter in the FreeBSD Handbook
Testing: New chapter in the FreeBSD Developers' Handbook:
NOTE: This project is more exploratory at the beginning. Requirements may change during the writing stage.
Preparation tasks include: * Reviewing current documentation and notes on developer testing frameworks, practices, etc. for FreeBSD and other BSD(s). * Current or older FreeBSD documentation and notes. For example: * TestSuite: https://wiki.freebsd.org/TestSuite * Old ""TestingFreeBSD"" page: https://wiki.freebsd.org/TestingFreeBSD * Current documentation and notes from related projects. For example: * http://wiki.netbsd.org/tutorials/atf/ * Primary documentation of the tools involved. For example: * Kyua testing framework: https://github.com/jmmv/kyua/ * Automated Testing Framework (ATF): https://github.com/jmmv/atf/ * Installing and configuring the relevant frameworks to gain familiarity. * Using the testing frameworks to run current tests. * Writing a small number of new tests. * (VERY important) Consulting with readers (software developers and testers) on what they want to see in the chapter.
The exact organization of the documentation is to be determined. However, after reading the chapter, the reader should be able to do the following at a minimum:
- Install and configure the testing frameworks for the purposes of testing FreeBSD.
- Write a test for the testing framework.
- Run a test in the testing framework.
The following will be emphasized where possible: * maximizing automation to reduce the work in setting up the test infrastructure, writing tests, and running tests. * adding test cases whenever a new bug is fixed. * comprehensive automated regression testing. * (where applicable) covering examples of standard testing scenarios, such as unit testing, functional testing, load testing, and so on.
Where possible, the goal is to not just explain and guide the developer through the testing framework but hopefully keep the process as simple as possible so developers are encouraged to incorporate more testing, and new developers are not put off from contributing.
LDAP: Updated article merged into chapter in the FreeBSD Handbook:
Unlike the chapter on Testing, the scope of an updated article or chapter on LDAP is well understood.
The current chapter in the FreeBSD Handbook and the current article both contain a lot of useful information. However, they need to be updated. A new revision of the article, intended to become the new chapter, has been started but needs to be completed.
Tasks include: * Proofreading the current handbook chapter and current article. * In preparation for GSoD2020, an initial pass has been done. * Testing each section in the handbook to confirm what works and what needs to be revised. * In preparation for GSoD2020, the server configuration has been tested with improvements identified. * Other sections remaining. * Writing new content and revising current content. * Updated content has been started for the server section. It needs to be completed. * Other sections remaining. * Testing all content on clean FreeBSD systems after a final draft is complete. * This task is critical as it identifies any gaps.
The final article or handbook chapter is expected to contain the following sections:
(1) Introduction to LDAP (2) Server configuration: (a) An explanatory walkthrough of a basic but functional OpenLDAP server configuration on FreeBSD. (b) A complete example of a basic but functional OpenLDAP server configuration, e.g. the result of (2a), on FreeBSD.
""Basic but functional"" includes configuration of the server with hashed passwords, secure connections over the network, and simulated but representative example user data.
(Optional - To be decided during GSoD2020) The server configuration may also include equivalent coverage of 389 Directory Server in FreeBSD. There was experimental FreeBSD support in 389 Directory Server but its current status needs to be confirmed.
(3) Client configuration: (a) An explanatory walkthrough of a functional client configuration on FreeBSD that can connect with the example server connection provided in (2). (b) A complete example of a functional client configuration, e.g. the result of (3a), on FreeBSD.
The client configuration section will include subsections on the following: * Pluggable Authentication Module (PAM), e.g. pam_ldap, pam_mkhomedir, nss-pam-ldapd * Name Service Switch (NSS), e.g. nss_ldap, nss-pam-ldapd * (Optional - To be decided during GSoD2020) SSSD - The status of SSSD in production in FreeBSD needs to be confirmed. * (Optional - To be decided during GSoD2020) FreeIPA - The use and functionality of FreeIPA in FreeBSD needs to be investigated. FreeIPA covers more than just LDAP so the scope of the FreeIPA configuration must be evaluated before inclusion in this handbook chapter.
(4) Security Considerations * The current version of the article includes a section on security considerations. Some of this content may be moved to the relevant section. However, there should still be a dedicated section on security considerations for reference purposes.
(5) Troubleshooting * Strategies for troubleshooting LDAP configuration.
(6) OpenSSL appendix
With the updated handbook chapter / article, the reader can take two clean FreeBSD systems, set up an LDAP server and LDAP client, and authenticate the client against the server.
After reading the updated handbook chapter / article, the reader should have the foundation necessary to take other more specialized or comprehensive documentation, e.g. OpenLDAP documentation, LDAP RFCs, and build or refine their FreeBSD LDAP configuration to meet their requirements.