Add Foreman 3.10 manual

_config.yml

@@ -85,6 +85,7 @@ plugins:
 
 foreman_versions:
   - nightly
+  - "3.10"
   - "3.9"
   - "3.8"
   - "3.7"

_includes/manuals/3.10/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.10/1.2_release_notes.md

@@ -0,0 +1,128 @@
+## Release notes for {{page.version}}
+
+This section will be updated prior to the next release.
+
+### Headline features
+
+#### Preparing for Ruby 3
+
+This release includes some features that are preparing the project to run on Ruby 3. As this is a large endeavour, it will take multiple releases and features to complete. See some of the features in the release notes for more details.
+
+#### foreman-debug is now an optional package
+
+The foreman-debug package is no longer installed by default, and it is now required to be installed separately.
+
+### Upgrade warnings
+
+### Deprecations
+
+### Release Notes
+
+### Release notes for 3.10.0
+#### Foreman
+* Unpin adobe/css-tools ([#37128](https://projects.theforeman.org/issues/37128))
+* Clean up old storybook dependencies ([#37127](https://projects.theforeman.org/issues/37127))
+* Replace \`node-sass\` with \`sass\` ([#37126](https://projects.theforeman.org/issues/37126))
+* Prepare STI usage to be compatible with Ruby 3.0 ([#37087](https://projects.theforeman.org/issues/37087))
+* Replace "apt-key" on Debian/Ubuntu in "global_registration.erb" ([#37034](https://projects.theforeman.org/issues/37034))
+* katello-certs-check should succeed if intermediates are presented without root ([#37021](https://projects.theforeman.org/issues/37021))
+* \`hammer host-registration generate-command\` doesn't accept \`unlimited\` as JWT life time
+ ([#36972](https://projects.theforeman.org/issues/36972))
+* Registration command should not fail with status 0 ([#36969](https://projects.theforeman.org/issues/36969))
+* Broken link in Register Host documentation  ([#36966](https://projects.theforeman.org/issues/36966))
+* Revert back 'Change Puppet CA' action ([#36955](https://projects.theforeman.org/issues/36955))
+* Switch to using terser for minification and compression of JS assets ([#36936](https://projects.theforeman.org/issues/36936))
+* Run Foreman tests on Ruby 3.0 ([#36849](https://projects.theforeman.org/issues/36849))
+* VM tab (legacy UI) shows error in case host is not associated to VM ([#36744](https://projects.theforeman.org/issues/36744))
+* Ubuntu version "nil" is interpreted as "0" ([#36741](https://projects.theforeman.org/issues/36741))
+
+#### Foreman - API
+* Create API for getting permissions of current user ([#36917](https://projects.theforeman.org/issues/36917))
+
+#### Foreman - Compute resources
+* Image-based deployment on Proxmox fails due to extra newline in "remote_execution_ssh_keys" snippet ([#37142](https://projects.theforeman.org/issues/37142))
+
+#### Foreman - Compute resources - VMware
+* VmWare - API doesn't show same info about VM as in UI ([#35248](https://projects.theforeman.org/issues/35248))
+
+#### Foreman - Host creation
+* Drop append domain names setting ([#36160](https://projects.theforeman.org/issues/36160))
+
+#### Foreman - Inventory
+* Changing the "Show New Host Overview Page" setting is not applied even after reloading the page
+ ([#37013](https://projects.theforeman.org/issues/37013))
+
+#### Foreman - JavaScript stack
+* Duplicate ids from webpack style ([#37173](https://projects.theforeman.org/issues/37173))
+* Load plugin public folder for webpack ([#37161](https://projects.theforeman.org/issues/37161))
+* "Component name already taken" warnings fix ([#37154](https://projects.theforeman.org/issues/37154))
+* Update to webpack 5 ([#37102](https://projects.theforeman.org/issues/37102))
+* BreadcrumbBar.test.js missing await ([#37070](https://projects.theforeman.org/issues/37070))
+* EditorView snapshots change because of classnames update ([#37026](https://projects.theforeman.org/issues/37026))
+* Rename interface to host_interface ([#36959](https://projects.theforeman.org/issues/36959))
+* Wrap script tags in content_for(:javascripts) ([#36958](https://projects.theforeman.org/issues/36958))
+
+#### Foreman - Parameters
+* Adding a new boolean-type parameter to a host causes an error ([#37012](https://projects.theforeman.org/issues/37012))
+
+#### Foreman - Realm
+* Grammatical error in Realm description in WebUI ([#37120](https://projects.theforeman.org/issues/37120))
+
+#### Foreman - Reporting
+* Getting "undefined method '#name' for NilClass::Jail (NilClass) (Safemode::NoMethodError)" error generating subscription report  ([#37016](https://projects.theforeman.org/issues/37016))
+* Hammer Report-Template Complains about 'Input Days from Now' Being Blank ([#32359](https://projects.theforeman.org/issues/32359))
+
+#### Foreman - Settings
+* Updating setting host_owner fails with "Value Host owner is invalid" ([#37015](https://projects.theforeman.org/issues/37015))
+
+#### Foreman - Templates
+* Support safe navigation operator in safemode ([#37010](https://projects.theforeman.org/issues/37010))
+
+#### Foreman - Tests
+* Drop unused react-dnd-test-utils package ([#37115](https://projects.theforeman.org/issues/37115))
+* Drop single_test  dependency ([#37093](https://projects.theforeman.org/issues/37093))
+* Use minitest_reporters_github in GitHub Actions ([#37092](https://projects.theforeman.org/issues/37092))
+* Incorrect Debian/Ubuntu release names in factories ([#37019](https://projects.theforeman.org/issues/37019))
+
+#### Foreman - Unattended installations
+* Satellite 6.12 is still using katello-ca to register hosts during provisioning instead of Gloabl Registration Template ([#36747](https://projects.theforeman.org/issues/36747))
+
+#### Foreman - Users, Roles and Permissions
+* Monitor > Host statuses ignores taxonomy scoping and user's permissions and shows counts even though the user can't see the actual hosts ([#37039](https://projects.theforeman.org/issues/37039))
+
+#### Foreman - Web Interface
+* Duplicate html-id on Settings-page ([#37168](https://projects.theforeman.org/issues/37168))
+* Pin victory-core to pre-36.9.0 ([#37156](https://projects.theforeman.org/issues/37156))
+* Host details - sub tabs are hidden ([#37089](https://projects.theforeman.org/issues/37089))
+* Show current user in the navigation when screen too small ([#37079](https://projects.theforeman.org/issues/37079))
+* Closing parent nav should also close child nav ([#37067](https://projects.theforeman.org/issues/37067))
+* Duplicate id in HTML ([#37066](https://projects.theforeman.org/issues/37066))
+* Login-Page missing background after scrolling ([#37064](https://projects.theforeman.org/issues/37064))
+* Total and owned links in Monitor > Host statuses have the links swapped in the error column ([#37038](https://projects.theforeman.org/issues/37038))
+* Expanding a section should collapse other expanded sections ([#37025](https://projects.theforeman.org/issues/37025))
+* Table index new button alignment in large screens ([#36963](https://projects.theforeman.org/issues/36963))
+* Clear navigation search doesn't clear results ([#36949](https://projects.theforeman.org/issues/36949))
+* Navigation Search doesnt show ansible roles ([#36948](https://projects.theforeman.org/issues/36948))
+* User dropdown shifted to the left when using foreman with plugins ([#36896](https://projects.theforeman.org/issues/36896))
+* Banner to show foreman instance  ([#36872](https://projects.theforeman.org/issues/36872))
+
+#### Installer
+* Installer doesn't set correct permissions of /pub/ files ([#37130](https://projects.theforeman.org/issues/37130))
+* Katello certificate tarball is actually .tar.gz instead of .tar ([#37097](https://projects.theforeman.org/issues/37097))
+* Rename deprecated pulp TELEMETRY setting to ANALYTICS ([#37062](https://projects.theforeman.org/issues/37062))
+
+#### Packaging
+* Make foreman-debug optional ([#37022](https://projects.theforeman.org/issues/37022))
+
+#### Packaging - RPMs
+* Add python-setuptools as an installation dependency for EL6 katello-host-tools ([#37106](https://projects.theforeman.org/issues/37106))
+
+*A full list of changes in 3.10.0 is available via [Redmine](https://projects.theforeman.org/issues?set_filter=1&sort=id%3Adesc&status_id=closed&f[]=cf_12&op[cf_12]=%3D&v[cf_12]=1789)*
+
+### Contributors
+
+We'd like to thank the following people who contributed to the Foreman {{page.version}} release:
+
+Adam Růžička,Archana Kumari,Bastian Schmidt,Dirk Götz,Eric Helms,Erik Berg,Evgeni Golov,Ewoud Kohl van Wijngaarden,Gaurav Talreja,Girija Soni,Gordon Bleux,Griffin Sullivan,Griffin-Sullivan,Ian Ballou,Jan Bundesmann,Karolina Malyjurkova,Leos Stejskal,Maria Agaphontzev,Markus Bucher,Markus Reisner,Martin Alfke,Maximilian Kolb,Michal Barecki,Nofar Alfassi,Oleh Fedorenko,Ottavia Balducci,Pat Riehecky,Quinn James,Ron Lavi,Samir Jha,Tim Meusel,William Bradford Clark
+
+As well as all users who helped test releases, report bugs and provide feedback on the project.

_includes/manuals/3.10/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.10/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.