Add manual section for Foreman 3.9

_includes/manuals/3.9/1.1_architecture.md

@@ -0,0 +1,17 @@
+
+## Foreman Architecture
+
+A Foreman installation will always contain a central Foreman instance
+that is responsible for providing the Web based GUI, node
+configurations, initial host configuration files, etc. However, if the
+Foreman installation supports unattended installations, then other
+operations need to be performed to fully automate this process. The
+Smart Proxy manages remote services and is generally installed with all
+Foreman installations to manage TFTP, DHCP, DNS, Puppet, Puppet CA,
+Ansible, and Salt.
+
+## Smart-Proxy
+
+A [Smart-Proxy](manuals/{{page.version}}/index.html#4.3SmartProxies) is located on or near a machine that performs a specific function and helps Foreman orchestrate the process of commissioning a new host. Placing the Smart Proxy on or near to the actual service will also help reduce latency in large distributed organizations.
+
+![Foreman Architecture](/static/images/foreman_architecture.png)

_includes/manuals/3.9/1.2_release_notes.md

@@ -0,0 +1,29 @@
+## Release notes for {{page.version}}
+
+This section will be updated prior to the next release.
+
+### Headline features
+
+### Upgrade warnings
+
+#### `ct_command` and `fcct_command` settings replaced with `(fc)ct_location` and `(fc)ct_arguments`
+
+To fix [CVE-2022-3874](/security.html#2022-3874) the settings for the CoreOS and Fedora CoreOS
+transpiler commands were changed to individual settings for the location of the binary and the
+arguments passed to it.
+During the upgrade the location of the binaries will be automatically changed to `/usr/bin/ct`
+and `/usr/bin/fcct`. Setting the binary location to any other path requires changes to
+`settings.yaml`, as different locations are forbidden by default.
+The arguments are automatically migrated from the old settings to the new ones.
+
+### Deprecations
+
+### Release Notes
+
+### Contributors
+
+We'd like to thank the following people who contributed to the Foreman {{page.version}} release:
+
+<!-- update scripts/committers.rb with the correct versions and dates and fill this in -->
+
+As well as all users who helped test releases, report bugs and provide feedback on the project.

_includes/manuals/3.9/2.1_quickstart_installation.md

@@ -0,0 +1,153 @@
+[The Foreman installer](/manuals/{{page.version}}/index.html#3.2ForemanInstaller) uses Puppet **(6 or later required)** to install Foreman. This guide assumes that you have a newly installed operating system, on which the installer will setup Foreman, a Puppet server, and the [Smart Proxy](/manuals/{{page.version}}/index.html#4.3SmartProxies) by default. It's **not advisable** to follow the steps below on an existing system, since the installer will affect the configuration of several components.
+
+<div class="alert alert-info">
+
+If you want to manage content (for example, RPMs, Kickstart trees, ISO and KVM images, OSTree content, and more) with Foreman please follow the  <a href="https://theforeman.org/plugins/katello/">Katello</a> installation instructions. If you are a new user, ensure that you familiarize yourself with  <a href="https://theforeman.org/plugins/katello/">Katello</a> and decide whether you want to use its features because installing Katello on top of an existing Foreman is unsupported. Note that you cannot install Katello on Debian systems.
+
+</div>
+
+
+#### Select operating system
+
+<script type="text/javascript">
+function update_quickstart_os(select) {
+  var os = select.value;
+  $(".quickstart_os").hide();
+  if (os && os != 'none') {
+    $(".quickstart_os_"+os).show();
+  } else {
+    $(".quickstart_os_none").show();
+  }
+}
+</script>
+
+To provide specific installation instructions, please select your operating system:
+<select onChange="update_quickstart_os(this);">
+  <option value="none">-- select operating system --</option>
+  <option value="el8">Enterprise Linux 8</option>
+  <option value="debian11">Debian 11 (Bullseye)</option>
+  <option value="ubuntu2004">Ubuntu 20.04 (Focal)</option>
+</select>
+
+#### Repositories
+
+<div class="quickstart_os quickstart_os_none">
+  <i>No operating system selected.</i>
+</div>
+
+<div class="quickstart_os quickstart_os_el8">
+  <p>
+    Enable Puppet's 7.x repository:
+  </p>
+
+{% highlight bash %}
+sudo dnf -y install https://yum.puppet.com/puppet7-release-el-8.noarch.rpm
+{% endhighlight %}
+</div>
+
+<div class="quickstart_os quickstart_os_el8">
+  <p>Enable the Foreman repositories:</p>
+
+{% highlight bash %}
+sudo dnf -y install https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm
+{% endhighlight %}
+</div>
+
+<div class="quickstart_os quickstart_os_el8">
+  <p>Enable the Foreman module:</p>
+
+{% highlight bash %}
+sudo dnf -y module enable foreman:el8
+{% endhighlight %}
+</div>
+
+<div class="quickstart_os quickstart_os_debian11">
+  <p>
+    Enable Puppet's 7.x repository:
+  </p>
+
+{% highlight bash %}
+sudo apt-get -y install ca-certificates
+cd /tmp && wget https://apt.puppet.com/puppet7-release-bullseye.deb
+sudo apt-get install /tmp/puppet7-release-bullseye.deb
+{% endhighlight %}
+
+  <p>Enable the Foreman repositories:</p>
+
+{% highlight bash %}
+sudo wget https://deb.theforeman.org/foreman.asc -O /etc/apt/trusted.gpg.d/foreman.asc
+echo "deb http://deb.theforeman.org/ bullseye {{page.version}}" | sudo tee /etc/apt/sources.list.d/foreman.list
+echo "deb http://deb.theforeman.org/ plugins {{page.version}}" | sudo tee -a /etc/apt/sources.list.d/foreman.list
+{% endhighlight %}
+</div>
+
+<div class="quickstart_os quickstart_os_ubuntu2004">
+  <p>
+    Enable Puppet's 7.x repository:
+  </p>
+
+{% highlight bash %}
+sudo apt-get -y install ca-certificates
+cd /tmp && wget https://apt.puppet.com/puppet7-release-focal.deb
+sudo apt-get install /tmp/puppet7-release-focal.deb
+{% endhighlight %}
+
+  <p>Enable the Foreman repositories:</p>
+
+{% highlight bash %}
+sudo wget https://deb.theforeman.org/foreman.asc -O /etc/apt/trusted.gpg.d/foreman.asc
+echo "deb http://deb.theforeman.org/ focal {{page.version}}" | sudo tee /etc/apt/sources.list.d/foreman.list
+echo "deb http://deb.theforeman.org/ plugins {{page.version}}" | sudo tee -a /etc/apt/sources.list.d/foreman.list
+{% endhighlight %}
+</div>
+
+#### Downloading the installer
+
+<div class="quickstart_os quickstart_os_none">
+  <i>No operating system selected.</i>
+</div>
+
+<div class="quickstart_os quickstart_os_el8">
+{% highlight bash %}
+sudo dnf -y install foreman-installer
+{% endhighlight %}
+</div>
+
+<div class="quickstart_os quickstart_os_debian11 quickstart_os_ubuntu2004">
+{% highlight bash %}
+sudo apt-get update && sudo apt-get -y install foreman-installer
+{% endhighlight %}
+</div>
+
+#### Running the installer
+
+<div class="quickstart_os quickstart_os_debian11 quickstart_os_ubuntu2004 alert alert-info">
+  Ensure that <code>ping $(hostname -f)</code> shows the real IP address, not 127.0.1.1.  Change or remove this entry from /etc/hosts if present.
+</div>
+
+The installation run is non-interactive, but the configuration can be customized by supplying any of the options listed in `foreman-installer --help`, or by running `foreman-installer -i` for interactive mode.  More examples are given in the [Installation Options](/manuals/{{page.version}}/index.html#3.2.2InstallerOptions) section.  Adding `-v` will disable the progress bar and display all changes.  To run the installer, execute:
+
+<div class="quickstart_os quickstart_os_none quickstart_os_debian11 quickstart_os_ubuntu2004 quickstart_os_el8">
+{% highlight bash %}
+sudo foreman-installer
+{% endhighlight %}
+</div>
+
+After it completes, the installer will print some details about where to find Foreman and the Smart Proxy. Output should be similar to this:
+
+{% highlight bash %}
+  * Foreman is running at https://theforeman.example.com
+      Initial credentials are admin / 3ekw5xtyXCoXxS29
+  * Foreman Proxy is running at https://theforeman.example.com:8443
+  The full log is at /var/log/foreman-installer/foreman-installer.log
+{% endhighlight %}
+
+#### Next-generation documentation
+
+Over the last year, Foreman community members have been open-sourcing Red Hat documentation to make more comprehensive guides available to Foreman users. At the moment, the following guides have been migrated to a work-in-progress [Foreman and Katello documentation site](https://docs.theforeman.org). This project is not yet complete, but you might find useful information in some of the following guides:
+
+* [Provisioning Guide](https://docs.theforeman.org/master/Provisioning_Guide/index-foreman.html)
+* [Administering Foreman Guide](https://docs.theforeman.org/master/Administering_Red_Hat_Satellite/index-foreman.html)
+* [Managing Hosts Guide](https://docs.theforeman.org/master/Managing_Hosts/index-foreman.html)
+* [Content Management Guide](https://docs.theforeman.org/master/Content_Management_Guide/index-foreman.html)
+* [Configuring Smart Proxies with a Load Balancer](https://docs.theforeman.org/master/Configuring_Load_Balancer/index-foreman.html)

_includes/manuals/3.9/2.2_quickstart_puppet.md

@@ -0,0 +1,39 @@
+
+After installation, the Foreman installer will have set up a Puppet server on the host, fully integrated with Foreman.  First run the Puppet agent on the Foreman host which will send the first Puppet report to Foreman, automatically creating the host in Foreman's database.
+
+{% highlight bash %}
+sudo puppet agent --test
+{% endhighlight %}
+
+<div class="alert alert-info">Puppet will show a warning the first time that the node can't be found, this can be ignored.</div>
+
+In Foreman, click on the *Hosts* tab and your Foreman host should be visible in the list with an "O" status.  This indicates its status is OK, with no changes made on the last Puppet run.
+
+#### Downloading a Puppet module
+
+Next, we'll install a Puppet module for managing the NTP service from [Puppet Forge](http://forge.puppetlabs.com) to our "production" environment (the default):
+
+{% highlight bash %}
+sudo puppet module install puppetlabs/ntp
+{% endhighlight %}
+
+In Foreman, go to *Configure > Classes* and click *Import from hostname* (top right) to read the available Puppet classes from the Puppet server and populate Foreman's database.  The "ntp" class will appear in the Puppet class list if installed correctly.
+
+#### Using the Puppet module
+
+Click on the "ntp" class in the list, change to the *Smart Class Parameters* tab and select the *servers* parameter on the left hand side.  Tick the *Override* checkbox so Foreman manages the "servers" parameter of the class and change the default value if desired, before submitting the page.
+
+* More info: [Parameterized classes documentation](/manuals/{{page.version}}/index.html#4.2.5ParameterizedClasses)
+* Screencast: [Parameterized class support in Foreman](https://www.youtube.com/watch?v=Ksr0tilbmcc)
+
+Change back to the *Hosts* tab and click *Edit* on the Foreman host.  On the *Puppet Classes* tab, expand the *ntp* module and click the + icon to add the *ntp* class to the host, then save the host.
+
+<div class="alert alert-info">Managed parameters can be overridden when editing an individual host from its <i>Parameters</i> tab.</div>
+
+Clicking the *YAML* button when back on the host page will show the *ntp* class and the servers parameter, as passed to Puppet via the ENC (external node classifier) interface.  Re-run `puppet agent --test` on the Foreman host to see the NTP service automatically reconfigured by Puppet and the NTP module.
+
+#### Adding more Puppet-managed hosts
+
+Other hosts with Puppet agents installed can use this Puppet server by setting `server = foreman.example.com` in puppet.conf.  Sign their certificates in Foreman by going to *Infrastructure > Smart Proxies > Certificates* or using `puppet cert list` and `puppet cert sign` on the Puppet server.
+
+Puppet classes can be added to host groups in Foreman instead of individual hosts, enabling a standard configuration of many hosts simultaneously.  Host groups are typically used to represent server roles.

_includes/manuals/3.9/2_quickstart_guide.md

@@ -0,0 +1,16 @@
+
+The Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup.  It uses native OS packaging (e.g. RPM and .deb packages) and adds necessary configuration for the complete installation.
+
+Components include the Foreman web UI, Smart Proxy, a Puppet server, and optionally TFTP, DNS and DHCP servers. It is configurable and the Puppet modules can be read or run in "no-op" mode to see what changes it will make.
+
+The installation will require 4GB of memory, see [System Requirements](manuals/{{page.version}}/index.html#3.1SystemRequirements) for more information.
+
+#### Supported platforms
+
+* Enterprise Linux 8, x86_64
+* Debian 11 (Bullseye), amd64
+* Ubuntu 20.04 (Focal), amd64
+
+#### Enterprise Linux
+
+The Foreman packages and installer are tested on AlmaLinux 8 and CentOS 8 Stream, but other RHEL derivatives can work because they're similar. Sometimes additional work may be needed. For any queries for these platforms raise a question in [discourse support section](https://community.theforeman.org/c/support/10)

_includes/manuals/3.9/3.1.1_supported_platforms.md

@@ -0,0 +1,36 @@
+The following operating systems are supported by the installer, have packages and are tested for deploying Foreman:
+
+* Red Hat Enterprise Linux 8
+  * Architectures: x86_64 only
+  * Apply all SELinux-related errata.
+* CentOS 8 Stream
+  * Architectures: x86_64 only
+  * **Note:**
+    - The RPM packages are built on CentOS Linux 8, but tested to work also on CentOS 8 Stream
+    - EPEL 8 is incompatible, enabling will cause package dependency issue.
+* Ubuntu 20.04 (Focal)
+  * Architectures: amd64
+* Debian 11 (Bullseye)
+  * Architectures: amd64
+
+PostgreSQL version 10 or newer.
+
+It is recommended to apply all OS updates if possible.
+
+All platforms will require Puppet 6 or higher, which may be installed from Puppet's repositories.
+
+Other operating systems will need to use alternative installation methods, such as from source.
+
+The following operating systems are known to install successfully from Foreman:
+
+* Enterprise Linux (RHEL, AlmaLinux, CentOS, Oracle Linux, Rocky Linux)
+* Fedora
+* Ubuntu
+* Debian
+* OpenSUSE
+* SLES
+* CoreOS
+* Solaris
+* FreeBSD
+* Juniper Junos
+* Cisco NX-OS

_includes/manuals/3.9/3.1.2_hardware_requirements.md

@@ -0,0 +1,18 @@
+
+The hardware requirements for Foreman depend primarily on the number of requests that it will receive, which depends on the number of configuration management clients, web UI activity and other systems using the API.
+
+The default installation when including Puppet server will require:
+
+* 4GB memory
+* 2GB disk space
+
+For a bare minimum installation with few clients and no Puppet server, the requirements are:
+
+* 2GB memory
+* 1GB disk space
+
+#### Scaling notes
+
+* The default Puma configuration is 2 workers with a maximum of 16 threads and a minimum of 0 threads per worker.
+* When using a Puppet server, consult the requirements outlined in the [Puppet server system requirements](https://puppet.com/docs/puppet/latest/server/install_from_packages.html#system-requirements).
+* Disk usage will increase as more data is stored in the database, mostly for facts and reports. See the [reports cronjob configuration](manuals/{{page.version}}/index.html#3.5.4PuppetReports) to change how they are expired.

_includes/manuals/3.9/3.1.3_puppet_versions.md

@@ -0,0 +1,45 @@
+Foreman integrates with Puppet and Facter in a few places, but generally using a recent, stable version will be fine.  The exact versions of Puppet, Puppetserver and Facter that Foreman is compatible with are listed below.
+
+<table class="table table-bordered table-condensed">
+  <tr>
+    <th>Puppet version</th>
+    <th>Foreman installer (AIO)</th>
+    <th>Foreman installer (non-AIO)</th>
+    <th>Smart Proxy</th>
+  </tr>
+  <tr>
+    <td>0.x-5.x</td>
+    <td>Not supported</td>
+    <td>Not supported</td>
+    <td>Not supported</td>
+  </tr>
+  <tr>
+    <td>6.x</td>
+    <td>Not supported</td>
+    <td>Not supported</td>
+    <td>Deprecated</td>
+  </tr>
+  <tr>
+    <td>7.x</td>
+    <td>Supported</td>
+    <td>Untested</td>
+    <td>Supported</td>
+  </tr>
+</table>
+
+#### AIO installer compatibility
+
+The Foreman installer has code for both AIO and non-AIO configurations, switching behavior automatically based on the version of Puppet installed (usually during the first run when answers are stored). Only AIO installations are tested.
+
+#### Puppet server compatibility
+
+Puppetserver is the application for serving Puppet agents used by default since Puppet 4. Both Fedora and Debian have not packaged Puppetserver for their non-AIO packages. The Puppetlabs packages must be used.
+
+#### Facter compatibility
+
+Foreman is known to be compatible with all Facter 2.x to 4.x releases.
+
+#### Puppet Enterprise compatibility
+
+The Foreman installer and packages are generally incompatible with Puppet Enterprise, however with some manual reconfiguration, individual Foreman components such as the smart proxy should work if needed (some further unsupported documentation can be found on the wiki).  The installer in particular will conflict with a Puppet Enterprise installation.  It is recommended that Foreman is installed using [Puppet "open source"](http://docs.puppetlabs.com/guides/installation.html).
+

_includes/manuals/3.9/3.1.4_browser_compatibility.md

@@ -0,0 +1,12 @@
+
+Using the most recent version of a major browser is highly recommended, as Foreman and the frameworks it uses offer limited support for older versions.
+
+The recommended requirements are as follows for major browsers:
+
+* Google Chrome - latest version
+* Microsoft Edge - latest version
+* Apple Safari - latest version
+* Mozilla Firefox - latest version
+* Mozilla Firefox Extended Support Release (ESR) - latest version
+
+Other browsers may work unpredictably.