(SIMP-8617) Move up the FAQ and HOWTO entries (#397)

Moved things up and converted them to the new style guide.

SIMP-8617 #close

docs/FAQ/00_SIMP_Version_Guide.rst

@@ -0,0 +1,32 @@
+.. _faq-simp_version_guide:
+
+SIMP Version Guide
+==================
+
+The SIMP versioning system has caused some confusion over time and this
+document serves as the authoritative reference for clarification.
+
+Top-Level SIMP for 6.X+
+-----------------------
+
+.. NOTE::
+
+   This is the version number that you get when you run :command:`rpm -q simp`
+
+The top level SIMP version for SIMP releases from 6.0.0 onward will be
+following `Semantic Versioning 2.0.0`_.
+
+In short, this means (from the reference):
+
+Given a version number ``MAJOR.MINOR.PATCH``, increment the:
+
+#. ``MAJOR`` version when you make incompatible API changes
+#. ``MINOR`` version when you add functionality in a backwards-compatible manner
+#. ``PATCH`` version when you make backwards-compatible bug fixes
+
+Sub-Component Versioning
+------------------------
+
+For all versions of SIMP, sub-components generally follow `Semantic Versioning 2.0.0`_.
+
+.. _Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html

docs/help/FAQ/10_Password_Complexity.rst → docs/FAQ/10_Password_Complexity.rst

@@ -8,7 +8,7 @@ This is based off of an amalgam of various password policies and may vary based
 on individual policies that are set for your installation.
 
 The default complexity is enforced in both :term:`PAM` and :term:`LDAP`, which
-are managed by SIMP's ``pam`` and ``simp_openldap`` modules, respectively.
+are managed by SIMP's :pupmod:`simp/pam` and :pupmod:`simp/simp_openldap` modules, respectively.
 
 .. WARNING::
 
@@ -59,6 +59,6 @@ as follows:
 
 .. IMPORTANT::
 
-   Systems that use ``pam_cracklib`` may differ slightly in behavior from
-   systems that use ``pam_pwquality``. If issues are found, please file a bug
+   Systems that use :program:`pam_cracklib` may differ slightly in behavior from
+   systems that use :program:`pam_pwquality`. If issues are found, please file a bug
    with the :term:`OS` vendor noting the issue.

docs/help/FAQ/20_Root_Logins.rst → docs/FAQ/20_Root_Logins.rst

@@ -1,7 +1,7 @@
 .. _faq-root-login:
 
-How can the root user login
-===========================
+Enabling ``root`` Logins
+========================
 
 Keeping in line with general best practice, SIMP does not allow ``root`` to
 login to the system remotely or at local terminals by default.
@@ -13,7 +13,7 @@ Enabling Terminal Logins
 ------------------------
 
 To allow ``root`` to login at the terminal, you will need to set the
-``useradd::securetty`` ``Array`` to include all ``tty`` devices from which you
+:code:`useradd::securetty` ``Array`` to include all ``tty`` devices from which you
 wish to allow ``root`` access.
 
 For example, to allow the ``root`` user to login at the first three virtual
@@ -29,18 +29,11 @@ consoles and the first serial device, you would place the following in
      - ttyS0
 
 
-.. IMPORTANT::
-
-   If you are working on a system that was not installed from an ISO, you
-   should do this before running ``simp bootstrap``.  Otherwise, unless you have
-   set up other users, you may not be able to log into your system.
-
-
 Enabling Remote SSH Logins
 --------------------------
 
-If you need to allow remote ``root`` logins over SSH (we **highly** advise
-against this), you can add the following to :term:`hiera`:
+If you need to allow remote ``root`` logins over SSH (we **highly** advise against this), you can
+add the following to :term:`hiera`:
 
 .. code-block:: yaml
 

docs/FAQ/40_Audit_Syslog.rst

@@ -0,0 +1,16 @@
+.. _faq-audit-syslog:
+
+Why aren't audit logs being forwarded to syslog?
+================================================
+
+Audit logs can be sent to syslog in addition to being persisted locally in :file:`/var/log/audit`.
+By default, SIMP disables forwarding of audit logs due to the excessive size of the collected logs.
+
+When audit logs are sent to remote syslog servers, the logs can quickly overwhelm the underlying network.
+
+If forwarding of audit logs via syslog is appropriate for your site, you can enable that forwarding
+by setting the following in :term:`hiera`:
+
+.. code-block:: yaml
+
+   auditd::config::audisp::syslog::drop_audit_logs: false

docs/help/FAQ/Logrotate.rst → docs/FAQ/Logrotate.rst

@@ -3,29 +3,29 @@
 Why Does Logrotate Complain About Repeated Configuration Settings
 =================================================================
 
-As of SIMP 6.2.0, SIMP-managed ``logrotate`` rules are now in
-``/etc/logrotate.simp.d`` instead of ``/etc/logrotate.d``.  The rules in
-``/etc/logrotate.d`` are still applied, but ``logrotate`` is configured to read
-the rules in ``/etc/logrotate.simp.d``, first.
+As of SIMP 6.2.0, SIMP-managed :program:`logrotate` rules are now in
+:file:`/etc/logrotate.simp.d` instead of :file:`/etc/logrotate.d`.  The rules in
+:file:`/etc/logrotate.d` are still applied, but :program:`logrotate` is configured to read
+the rules in :file:`/etc/logrotate.simp.d` first.
 
 This change was made to ensure SIMP-managed rules take precedence over
 vendor-supplied rules. When multiple rules are specified for the same file, only
 the first rule is applied. Any subsequent rules are discarded.
 
 .. NOTE::
 
-   For some versions of ``logrotate``, a rule with a duplicate is discarded *in
+   For some versions of :program:`logrotate`, a rule with a duplicate is discarded *in
    its entirety*, even if only one of the managed log files is a duplicate.
    This means the remaining log files specified in that discarded rule will
    *not* be rotated!
 
-Because the location of the SIMP-managed ``logrotate`` rules has changed,
+Because the location of the SIMP-managed :program:`logrotate` rules has changed,
 any previously existing (but now obsolete) SIMP rules will still reside in
-``/etc/logrotate.d``.  Although these rules cause no issues with ``logrotate``,
+:file:`/etc/logrotate.d`.  Although these rules cause no issues with :program:`logrotate`,
 they may be confusing to system administrators.  So, you may wish to manually
 remove these rules.
 
-The following script can be used to identify obsolete SIMP ``logrotate`` rules
+The following script can be used to identify obsolete SIMP :program:`logrotate` rules
 and they can be removed manually as necessary.
 
 .. code-block:: sh

docs/help/FAQ/Omni_Env_Exists.rst → docs/FAQ/Omni_Env_Exists.rst

@@ -1,25 +1,25 @@
 .. _faq_omni_exists:
 
-OMNI Environment Already Exists Error
+Omni-Environment Already Exists Error
 =====================================
 
-This FAQ covers what to do when running ``simp config`` outputs an
+This FAQ covers what to do when running :command:`simp config` outputs an
 ``"Unable to configure: Invalid SIMP omni-environment for 'production' exists"`` error
 
 If installing SIMP on a system that has a pre-existing ``production`` :term:`Puppet Environment`,
-you may encounter the following error when running `simp config`:
+you may encounter the following error when running :command:`simp config`:
 
 .. code-block:: bash
 
-    Unabled to configure: Invalid SIMP omni-environment for 'production' exists:
+    Unable to configure: Invalid SIMP omni-environment for 'production' exists:
       >> Puppet environment 'production' exists
       >> Secondary environment 'production' does not exist
 
 or (depending on the version):
 
 .. code-block:: bash
 
-    Unable to configure: Invalid SIMP omni-environment for 'production' exists:
+    Unabled to configure: Invalid SIMP omni-environment for 'production' exists:
       >> Puppet environment 'production' exists
       >> Secondary environment 'production' does not exist
 
@@ -29,9 +29,9 @@ Resolution Options
 A New Start
 ^^^^^^^^^^^
 
-If you want to have a completely clean start, then just rename the production
-directory ``(/var/simp/environments/production)`` to ``production.bak`` and
-re-run ``simp config`` and ``simp bootstrap``.
+If you want to start clean, then just rename the :file:`production/`
+directory (:file:`/var/simp/environments/production`) to :file:`production.bak` and
+re-run :command:`simp config` and :command:`simp bootstrap`.
 
 A Different Environment
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/help/FAQ/Puppet.rst → docs/FAQ/Puppet.rst

@@ -17,9 +17,9 @@ troubleshoot the issue.
 #. Make sure that your system clocks are within one hour of each other.
 #. Ensure that the forward and reverse lookup for the FQDN of your systems is
    correct and matches the hostnames listed in the output of
-   ``openssl x509 -text -noout -in $(puppet config print hostcert) | less``
+   :command:`openssl x509 -text -noout -in $(puppet config print hostcert) | less`
 
-   HINT: Look at the `Subject` and `X509v3 Subject Alternative Name` sections.
+   HINT: Look at the ``Subject`` and ``X509v3 Subject Alternative Name`` sections.
 
 #. Check that the connection from the client system to the server can
    successfully connect:
@@ -32,9 +32,8 @@ troubleshoot the issue.
       -key $(puppet config print hostprivkey) \
       -CAfile $(puppet config print localcacert)
 
-If none of these items provides useful information, you may need to check
-permissions on your server and/or dig more closely into the puppetserver or
-client logs.
+If none of these items provides useful information, you may need to check permissions on your server
+and/or dig more closely into the :program:`puppetserver` or client logs.
 
 .. _faq-puppet-debug_mode_crash:
 
@@ -50,7 +49,7 @@ The bug `FACT-1732`_ can cause Facter to crash while attempting to print a
    Facts provided by SIMP's modules are **not affected** by FACT-1732.
 
 * This issue only affects facts introduced from *non-SIMP* sources.
-* It will cause the commands ``puppet agent -t --debug`` and ``facter -p``
+* It will cause the commands :command:`puppet agent -t --debug` and :command:`facter -p`
   to fail with errors when they encounter Bignum-sized *numeric* fact values.
 * You can fix your own facts to avoid FACT-1732 by returning any potentially
   large numeric value as a String.
@@ -59,7 +58,7 @@ The bug `FACT-1732`_ can cause Facter to crash while attempting to print a
 
 SIMP modules' facts haven't been susceptible to FACT-1732 since SIMP
 6.1.0-0.  Before that, the ``shmall`` and ``shmax`` facts from
-:program:`simp-simplib` would crash on systems with a lot of memory.
+:pupmod:`simp/simplib` would crash on systems with a lot of memory.
 
 .. _Bignum: https://ruby-doc.org/core-2.3.0/Bignum.html
 .. _FACT-1732: https://tickets.puppetlabs.com/browse/FACT-1732
@@ -68,36 +67,35 @@ SIMP modules' facts haven't been susceptible to FACT-1732 since SIMP
 
 .. _faq-puppet-generate_types:
 
-When should I run ``puppet generate types``?
---------------------------------------------
+When should I run :command:`puppet generate types`?
+---------------------------------------------------
 
-The ``puppet generate types`` command addresses the problem of `Puppet
+The :command:`puppet generate types` command addresses the problem of `Puppet
 Environment isolation`_ (`SERVER-94`_) by generating :term:`custom type`
 metadata definitions for each environment.  The command must therefore be
 re-run in response to changes in Puppet environments and compilers.
 
 By default, SIMP automates some of these cases using :program:`incron`
 triggers. However, there are still some situations where you will have to make
-sure that ``puppet generate types`` is run.
+sure that :command:`puppet generate types` is run.
 
 Situations :program:`incron` handles automatically
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, SIMP configures the :program:`incron` daemon to automatically run
-``puppet generate types`` under either of the following circumstances:
+:command:`puppet generate types` under either of the following circumstances:
 
-  * The ``puppet`` or ``puppetserver`` binaries have been updated.
+  * The :program:`puppet` or :program:`puppetserver` binaries have been updated.
   * A new :term:`Puppet environment` directory is added to the system.
 
-This behavior is managed by the Puppet class ``pupmod::master::generate_types``.
+This behavior is managed by the Puppet class :code:`pupmod::master::generate_types`.
 
 .. rubric:: Differences from Previous versions of SIMP
 
 Earlier versions of :program:`simp-pupmod` (7.6.0 through 7.7.1, shipped with
-SIMP 6.2.0-0 through 6.3.1-0) attempted to automatically trigger ``puppet
-generate types`` under every relevant circumstance.  However, some of the
-triggers could add too much load on the system and were removed from the
-:program:`incron`'s watchlist.
+SIMP 6.2.0-0 through 6.3.1-0) attempted to automatically trigger :command:`puppet generate types`
+under every relevant circumstance.  However, some of the triggers could add too much load on the
+system and were removed from the :program:`incron`'s watchlist.
 
 These situations must be addressed by other means (see below).
 
@@ -106,7 +104,7 @@ Situations :program:`incron` doesn't handle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :program:`incron` does not handle all cases, so you will need to ensure that
-``puppet generate types`` is after the following events:
+:command:`puppet generate types` is after the following events:
 
   * A new *module* that includes custom types is added to an existing environment.
   * An existing custom type's internal code is updated.
@@ -115,7 +113,7 @@ Situations :program:`incron` doesn't handle
 Generating types manually
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can run the ``puppet generate types`` command as **root** on the Puppet
+You can run the :command:`puppet generate types` command as **root** on the Puppet
 Server.  However, in order to ensure that the Puppet Server process can read
 the generated files, you must also ensure they have the correct ownership and
 permissions.  One way to do this is by running the following command:
@@ -131,11 +129,12 @@ Automatically generating types after ``r10k deploy environment``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are using :term:`r10k` to deploy :term:`Control Repository` branches
-using ``r10k deploy environment``, you can set the `"generate_types" option`_
+using :command:`r10k deploy environment`, you can set the `"generate_types" option`_
 in the :file:`r10k.yaml` file to automatically run :command:`puppet generate
 types` for each environment after it is deployed:
 
 .. code-block:: yaml
+
    :emphasize-lines: 3
    :caption: Inside :file:`r10k.yaml`:
 

docs/help/FAQ/Rsync.rst → docs/FAQ/Rsync.rst

@@ -3,7 +3,7 @@
 Why does SIMP use rsync?
 ========================
 
-SIMP uses `rsync` to manage both large files and large numbers of small files.
+SIMP uses :program:`rsync` to manage both large files and large numbers of small files.
 This is to reduce the number of resources in the catalog and take advantage of
 rsync's syncing engine to reduce network load and Puppet run times.
 
@@ -33,7 +33,7 @@ case, rsync saves bandwidth, Puppet run time, and a few CPU cycles.
 Large Numbers of Files
 ----------------------
 
-``named`` and ``dhcpd`` are the opposite situation. In both of these cases,
+:program:`named` and :program:`dhcpd` are the opposite situation. In both of these cases,
 they may manage large numbers of files.  Typically, like above, Puppet would
 have to checksum every file and see if it needed changing, with each file
 setting up a new connection to the Puppet server transferring each file
@@ -50,12 +50,12 @@ Where are the rsync files?
 --------------------------
 
 SIMP packages the rsync materials in the ``simp-rsync-skeleton`` RPM, which
-installs a file tree ``/usr/share/simp/environment-skeleton/rsync``. This
+installs a file tree :file:`/usr/share/simp/environment-skeleton/rsync`. This
 directory is automatically installed in the :term:`SIMP Secondary Environment`
-for the ``production`` :term:`SIMP Omni-Environment` created by ``simp config``
-(``/var/simp/environments/production``) or the corresponding directory
-for a new environment created by ``simp environment new``.
+for the ``production`` :term:`SIMP Omni-Environment` created by :command:`simp config`
+(:file:`/var/simp/environments/production`) or the corresponding directory
+for a new environment created by :command:`simp environment new`.
 
 The rsync directories in the SIMP Secondary Environment are shared by the
-``simp::server::rsync_shares`` class, which is included on the SIMP server if
-the ``simp_options::rsync`` catalyst is enabled.
+:code:`simp::server::rsync_shares` class, which is included on the SIMP server if
+the :code:`simp_options::rsync` catalyst is enabled.

docs/help/FAQ/Selinux.rst → docs/FAQ/Selinux.rst

@@ -1,19 +1,19 @@
 .. _faq-selinux:
 
-How to recover from SELINUX policy failure
-==========================================
+Recovering from SELINUX policy failures
+=======================================
 
-If you experience a failed boot after running ``simp bootstrap`` with an error
-that says something along the lines of ``Failed to load SELINUX policy,
-freezing``, follow these instructions:
+If you experience a failed boot after running :command:`simp bootstrap` with an error
+that says something along the lines of ``Failed to load SELINUX policy, freezing``, follow these
+instructions:
 
 #. Reboot into single user mode or a rescue shell (instructions on `EL6`_ and
-   `EL7`_). You may need your GRUB password that was set during ``simp
-   config`` or set using the ``simp-simp_grub`` module.
+   `EL7`_). You may need your GRUB password that was set during :command:`simp config` or set using
+   the :pupmod:`simp/simp_grub` module.
 
-#. Reinstall the selinux policy: ``yum reinstall -y selinux-policy-targeted``
+#. Reinstall the selinux policy: :command:`yum reinstall -y selinux-policy-targeted`
 
-#. Tell the kernel to relabel all files during next boot: ``touch /.autorelabel``
+#. Tell the kernel to relabel all files during next boot: :command:`touch /.autorelabel`
 
 #. Reboot