Developer Guide¶
Building a development environment¶
NEED CONTENT
Insert dev environment setup and test running instructions.
Writing documentation¶
Documentation for individual controls is automatically generated where possible. There is also the ability to add deployer notes for individual tasks that discuss the specific implementation or risks with running the task/etc. Variables that control the execution of each task are automatically pulled from the Ansible task files themselves.
Deployer notes¶
Deployer notes are optional and can be added for each control that needs
additional data to be provided to role users. The notes are simply rST
(reStructuredText) fragments and can contain simple blocks of text or
more complex rST formatted text. The system matches deployer notes to STIG
controls based on the note filename, which should follow the format
RHEL-07-010010.rst
.
All of the notes are found within doc/metadata/notes
. Here is an example:
The tasks in the security role enable the appropriate Linux Security Module
(LSM) for the operating system.
For Ubuntu, openSUSE and SUSE Linux Enterprise 12 systems, AppArmor is installed and
enabled. This change takes effect immediately.
For CentOS or Red Hat Enterprise Linux systems, SELinux is enabled (in
enforcing mode) and its user tools are automatically installed. If SELinux is
not in enforcing mode already, a reboot is required to enable SELinux and
relabel the filesystem.
.. warning::
Relabeling a filesystem takes time and the server must be offline for the
relabeling to complete. Filesystems with large amounts of files and
filesystems on slow disks will cause the relabeling process to take more
time.
Deployers can opt out of this change by setting the following Ansible variable:
.. code-block:: yaml
rhel7stig_disruption_high: no
The note should be brief, but it must answer a few critical questions:
- What does the change do to a system?
- What is the value of making this change?
- How can a deployer opt out or opt in for a particular change?
- Is there additional documentation available online that may help a deployer decide whether or not this change is valuable to them?
Run make html
from the doc/
directory to rebuild the documentation
and review your changes.