Problem: Out-of-date instructions in the main Foreman manual for v2.1.0 and likely earlier in “3.2.3 Installation Scenarios” (Foreman :: Manual)
There are two instances of the following:
Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from Administer > Settings > Authentication , and set the Foreman URL appropriately.
At least in Foreman 2.1.0 (and possibly earlier - not verified), the values for the mentioned OAuth Consumer settings are (I believe - correctly) redacted, as can be seen in this screen shot (logged in as “
The reader should instructed to run the following (or similar) command on the foreman server system, to extract the key and secret required for the procedure being documented:
sudo grep oauth_consumer_ /etc/foreman/settings.yaml
I’ll leave it to the documentation/developer teams to decide how they would like to document this procedure and whether to prefix the command with
sudo(8), or assume the user is running as
With encouragement from @mcorr in a previous topic, I’ll be bold and suggest the following:
Starting Assumption: By limitation or convention, subsection numbering only goes to three levels.
Section 3.2.3 “Installation Scenarios”, should be promoted to one level higher (say 3.3), so that each scenario can be given its own subsection numbering, and thus appear in the LHS Table of Contents when rendered online. So specifically, “Using an external database server”, “Setting up Foreman with additional Smart Proxies”, “Standalone Puppetserver”, … are promoted to be in the LHS ToC. And yes, I realize the “Installation Scenarios” are “Foreman Installer” installation scenarios, so the subsection heading may need to be changed.
The section “Setting up Foreman with additional Smart Proxies”, (sort of) just stops after outlining the required process in English. Especially the “
2. Run the standalone installation as detailed below”, as there is nothing below, as a new subsection starts on installing a “Standalone Puppetserver”.
I, in fact, blindly copied the command line example from the next subsection into my notes and updated with my details, and run that and it worked (for what I was testing - creating and registering another smart-proxy). Where as the actual commands to run (for provisioning tasks - my intention) are in the subsection “Smart proxy for DNS, DHCP etc.”. In fact, that last mentioned subsection mentions the certificate requirements from the first mentioned subsection.
Maybe these two subsections should be closer together or merged. I personally would like to see a small reminder sentence in each scenario, to remind the user why they might wish to undertake this scenario - for me - I wanted to test that I could deploy a smart-proxy at a simulated offsite location to install systems (actually VMs on VMware vSphere/ESXi). Without referring back to other documentation, I can’t as yet (as a new foreman user) answer the question: should I be configuring my remote smart-proxy with puppet? I know I need TFTP, DHCP, … to provision systems at that site, but do I need a proxy for puppet to provision my VMs? (Aside: I’m not using puppet to manage systems, so probably not, but I will be using Ansible, so should I configure the Ansible feature on the remote smart-proxy? For myself, refresher reading will be required as I design/build my first non-test Foreman VMs - I know I have read the answer to the questions I just posed, I just don’t remember design guidelines for these cases - but the overall concepts are slowly sinking in )
In the section “Setting up Foreman with additional Smart Proxies”. For users not versed in the puppet universe, the sentences proceeding each of the following commands "
puppet ssl bootstrap…" and "
puppetserver ca sign…", could be augmented with the host to run the command on; the first is the new smart-proxy only system, and second is the foreman-server system (if it is an all-in-one installation or your PuppetServer/CA system). While I knew which hosts to run which commands on, it is really not obvious from the documentation that this is required. Also a reminder that the firewall on the Foreman All-In-One (or PuppetServer/CA) will need to allow remote connections to the puppetserver process (on port 8140 by default) would be nice, as the error you get is cryptic (IIRC, “No route to host”, and not the expected “Connection refused”)
In “Setting up Foreman with additional Smart Proxies”, starts with scenario description (which is good), but sentences: “
On the Foreman host, run a complete foreman-installer all-in-one installation to provide Foreman, a Puppetserver and Smart Proxy. This will be the Puppet CA.” - I feel needs a little work, especially the “
This will be the Puppet CA.” part. Maybe just adding “
host”, after “
This” would work, but maybe it would be better to split sentences differently, and state that the default all-in-one foreman-installer server will host the foreman application and additionally act as a local smart-proxy, database server, puppetserver and puppet CA (Certificate Authority).
I hope this feedback has been a useful insight into one new user’s journey in to that small section of the documentation.