theforeman / foreman-documentation

Documentation for the Foreman Project and its ecosystem

Foreman documentation

This git repository contains the following documentation:

• Official documentation for the Katello project
• PoC of improving documentation for the Foreman project. See this milestone to check the progress.

For official Foreman documentation, see Foreman Manual.

Contributing

Contributions are welcome. Please, familiarize yourself with CONTRIBUTING and Contribution Guidelines for Foreman guides.

Repository content

Foreman guides

This is a tree of documentation based on Red Hat Satellite 6 official books. See README in the guides/ subdirectory for more information.

Static site

The landing page for docs.theforeman.org is available as a generated static site. The static content is always built from the master branch. See README in the web/ subdirectory for more information.

Testing locally

To build both static site and guides for easy local testing, there is the global Makefile in the root directory with the following targets:

• html: builds HTML guides with all contexts (foreman-el, foreman-deb, katello, satellite, and orcharhino)
• web: builds static site using the nanoc tool
• compile: compiles all content into a single directory ./result
• serve: serves the result directory via a python web server (the default target)

To test the whole site locally, perform make serve command and open up http://localhost:5000. Use PORT=5008 to change the web server port (5000 by default). It builds all contexts so the initial build can be slow, make sure to use -j option for faster builds on modern multi-core machines. Stable versions are symlink to the nightly (current) version, this can cause issues for deleted (or renamed) guides.

Deployment

Github actions perform HTML (with link validation) and WEB artifact creation and if succeeded and branch is master or stable, artifacts are downloaded, extracted and deployed (commited into gh-pages). Deployment does not delete files, in order to remove some unwanted content, manual deletion and push into gh-pages must be performed.

When a commit is pushed into master:

• All artifacts are built.
• Static WEB and HTML is downloaded and copied into / or /nightly respectively.
• Changes are pushed into gh-pages branch.

When a commit is pushed into X.Y:

• All artifacts are built.
• HTML artifact is downloaded and copied into /X.Y.
• Changes are pushed into gh-pages branch.

Branching new release

• Create a new X.Y branch.
  • Update guides/common/attributes.adoc
    • Set DocState to unsupported
    • Set ProjectVersion to X.Y and set the matching KatelloVersion
  • Push into X.Y branch.
• Update master
  • Update ProjectVersionPrevious to X.Y in guides/common/attributes.adoc
  • Create a copy of /web/content/release-nightly.md as release-X.Y.md and edit it accordingly.
  • Add the new release versions to the site's index page and navigation bar by editing /web/content/index.adoc and /web/content/js/versions.js.
  • Test the changes by following the instructions in /web/README.md to deploy the website locally.
  • Add the new Foreman version to /.github/PULL_REQUEST_TEMPLATE.md.
  • Update VERSION_LINKS in the root Makefile.
  • Push the changes into master.
• Check the site if links and landing page appeared correctly. HTML guides should be deployed into /X.Y

License

See LICENSE files in individual subdirectories.

foreman-documentation's Issues

Avoid /etc/foreman-installer/scenarios.d

This directory will be moved in the future (probably /var/lib/foreman-installer) to signify the user is not supposed to modify these files. The way I look at it is that it's similar to suggesting open a database console and SELECT * FROM settings rather than going to the settings page.

Would it be better to suggest foreman-installer --full-help and let users look at (default: $VALUE) instead? The benefit is that it's not scenario specific and always the same command. Note that --scenario $scenario only needs to be passed on the first installation. After that a scenario has been selected and will always be used.

Tech Previews still listed upstream in Admin guide

In the Administrating guide, tech previews are still listed:

http://docs.theforeman.org/guides/build/doc-Administering_Red_Hat_Satellite/index-foreman.html#chap-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Configuring_External_Authentication

Missing repos in Install guides

The Installing Foreman server guide in 2.1.1 Configuring Repositories does not enable some required repositories as described in the Foreman Manual]
Specifically, it does not enable the following two repos:

subscription-manager repos --enable rhel-7-server-optional-rpms
subscription-manager repos --enable rhel-7-server-extras-rpms

And it enables the following extra repos that must be removed from the guide:

--enable=rhel-7-server-satellite-6.7-rpms \
--enable=rhel-server-rhscl-7-rpms \
--enable=rhel-7-server-ansible-2.8-rpms

The same probably happens in the Smart Proxy guide.

Document behavior for various facts

Foreman performs some actions for some facts, according to its configuration. This can be often confusing for users, let's document it somewhere.

Fact name (type)	Description	Configurable
environment (Puppet)	Updates Host's Puppet environment from fact named "environment" or "agent_specified_environment" overwriting its previous value. If it does not exist, new record is created. If such fact does not exists, setting "Default Puppet environment" specifies the default value.	Administer - Setting - Puppet - Update environment from facts
model (Puppet)	Updates Hardware model of a host. If it does not exist, new record is created	No.
architecture (Puppet)	Updates Architecture for a host creating it if it does not exists. Value is normalized, for example "arm64" is change "aarch64". On Sun Microsystem operating systems, fact named "hardwareisa" is taken into account.
domain (Puppet)	Updates Domain of primary network interface of a host, creates new entry if it does not exist.	No
ipaddress, ipaddress6 (Puppet)	Updates Subnet of all interfaces according to the IPv4 or IPv6 reported via facts. Addresses which do not match existing subnets in Foreman are ignored.	Administer - Setting - Puppet - Update subnets from facts
foreman_organization (Puppet)	Updates hosts Organiaztion from a fact.	Fact name can be customized via Administer - Setting - Puppet - Organiaztion fact
foreman_location (Puppet)	Updates hosts Location from a fact.	Fact name can be customized via Administer - Setting - Puppet - Location fact
foreman_comment (Puppet)	Updates hosts description comment a fact.	No. This is still unmerged PR: theforeman/foreman#7482
system_uptime (Puppet), proc_stat.btime (RHSM)	Host uptime reported attribute is calculated from facts	No.
is_virtual (Puppet), virt.is_guest (RHSM)	Host virtual reported attribute is set from facts	No.
memory.system.total_bytes, memorysize_mb (Puppet), memory.memtotal (RHSM)	Host memory reported attribute is set from facts	No.
processors.physicalcount, physicalprocessorcount (Puppet), 'cpu.cpu_socket(s) (RHSM)	Host CPUs reported attribute is set from facts	No.
processors.count, processorcount (Puppet), cpu.core(s)_per_socket (RHSM)	Host cores reported attribute is set from facts	No.

When a host does not exist in Foreman database and new facts or report is sent, new host is created as unmanaged host (with no provisioning fields). This behavior can be changed via "Create new host when facts are uploaded" and "Create new host when report is uploaded" in Administer - Setting - Puppet.

@ekohl anything I missed? @shimstein @xprazak

Use of --foreman-proxy-dns-server in the Networking chapter

In the networking chapter there's --foreman-proxy-dns-server "192.168.140.2" but I don't see why. This can be localhost which is more likely to work. Note this is the address foreman-proxy uses to connect to the dns server. The default is 127.0.01 which should work.

Replace {project} {product version}

We would want to change the syntax to something much better. For example:

.For CLI Users

The compute profile CLI commands are not yet implemented in {ProjectName} {ProductVersion}.

Integrate pmdastatsd into Monitoring Guide

This can only be integrated after Satellite runs on RHEL 8 (PCP 5.x) because the agent will not be backported to RHEL7.

diff --git a/guides/doc-Monitoring_Guide/topics/con_pcp-metrics.adoc b/guides/doc-Monitoring_Guide/topics/con_pcp-metrics.adoc
index da0a051..01c5bbe 100644
--- a/guides/doc-Monitoring_Guide/topics/con_pcp-metrics.adoc
+++ b/guides/doc-Monitoring_Guide/topics/con_pcp-metrics.adoc
@@ -9,7 +9,7 @@ The value of a counter metric only increases. For example, a count of disk write
 
 In addition to system metrics such as CPU, memory, kernel, XFS, disk, and network, the following metrics are configured:
 
-[%header,cols=2*] 
+[%header,cols=2*]
 |===
 |Metric
 |Description
@@ -23,6 +23,6 @@ In addition to system metrics such as CPU, memory, kernel, XFS, disk, and networ
 |postgresql.*
 |Basic PostgreSQL statistics
 
-|mmv.fm_rails_*
+|statsd.fm_rails_*
 |Satellite metrics
 |===
diff --git a/guides/doc-Monitoring_Guide/topics/con_performance-metrics-domain-agents.adoc b/guides/doc-Monitoring_Guide/topics/con_performance-metrics-domain-agents.adoc
index fee6dd8..2f81469 100644
--- a/guides/doc-Monitoring_Guide/topics/con_performance-metrics-domain-agents.adoc
+++ b/guides/doc-Monitoring_Guide/topics/con_performance-metrics-domain-agents.adoc
@@ -1,4 +1,8 @@
 [id='performance-metric-domain-agents_{context}']
 = Performance Metric Domain Agents
 
-A Performance Metric Domain Agent (PMDA) is a PCP add-on which enables access to metrics of an application or service. To gather all metrics relevant to Satellite, you must install PMDAs for Apache HTTP Server and PostgreSQL.
\ No newline at end of file
+A Performance Metric Domain Agent (PMDA) is a PCP add-on which enables access to metrics of an application or service. To gather all metrics relevant to Satellite, you must install PMDAs for Statsd protocol, Apache HTTP Server and PostgreSQL.
+
+* pmdastatsd is used to gather telemetry data coming out of Ruby on Rails application in statsd format.
+* pmdaapache connects to Apache HTTP Server monitoring URL to get server statistics data.
+* pmdapostgres connect to PostgreSQL to get SQL related monitoring information.
diff --git a/guides/doc-Monitoring_Guide/topics/con_satellite_metrics_overview.adoc b/guides/doc-Monitoring_Guide/topics/con_satellite_metrics_overview.adoc
index a9b5107..77f07a6 100644
--- a/guides/doc-Monitoring_Guide/topics/con_satellite_metrics_overview.adoc
+++ b/guides/doc-Monitoring_Guide/topics/con_satellite_metrics_overview.adoc
@@ -9,6 +9,6 @@ You can collect the following metrics from Satellite:
 * Process statistics, including memory and CPU utilization;
 * Apache HTTP Server activity statistics;
 * PostgreSQL activity statistics;
-* Satellite application statistics.
+* Satellite application telemetry data.
 
 Use Performance Co-Pilot (PCP) to collect and archive Satellite metrics.
diff --git a/guides/doc-Monitoring_Guide/topics/proc_configuring-pcp-data-collection.adoc b/guides/doc-Monitoring_Guide/topics/proc_configuring-pcp-data-collection.adoc
index 7237876..3de0e72 100644
--- a/guides/doc-Monitoring_Guide/topics/proc_configuring-pcp-data-collection.adoc
+++ b/guides/doc-Monitoring_Guide/topics/proc_configuring-pcp-data-collection.adoc
@@ -149,19 +149,13 @@ If you find errors in `/var/log/pcp/pmcd/postgresql.log`, restart the *pmcd* ser
 
 . Enable telemetry functionality in Satellite.
 +
-To enable collection of metrics from Satellite, you must send metrics via the `statsd` protocol into the `pcp-mmvstatsd` daemon. The metrics are aggregated and available via the PCP MMV API.
+To enable collection of metrics from Satellite, you must send metrics via the `statsd` protocol into the `pmdastatsd`.
 
-.. Install the Foreman Telemetry and `pcp-mmvstatsd` packages.
+.. Install the Statsd reciever.
 +
 ----
-# yum install foreman-telemetry pcp-mmvstatsd
-----
-
-.. Enable and start the `pcp-mmvstatsd` service.
-+
-----
-# systemctl enable pcp-mmvstatsd
-# systemctl start pcp-mmvstatsd
+# cd /var/lib/pcp/pmdas/statsd
+# ./Install
 ----
 
 .. Enable the Satellite telemetry functionality.
@@ -174,7 +168,7 @@ Add the following lines to `/etc/foreman/settings.yaml` configuration file:
   :statsd:
     :enabled: true
     :host: '127.0.0.1:8125'
-    :protocol: 'statsd'
+    :protocol: 'datadog'
   :prometheus:
     :enabled: false
   :logger:
@@ -182,16 +176,6 @@ Add the following lines to `/etc/foreman/settings.yaml` configuration file:
     :level: 'INFO'
 ----
 
-. Schedule daily storage of metrics in archive files:
-+
-----
-# cat >/etc/cron.daily/refresh_mmv <<EOF
-#!/bin/bash
-echo "log mandatory on 1 minute mmv" | /usr/bin/pmlc -P
-EOF
-# chmod +x /etc/cron.daily/refresh_mmv
-----
-
 . Restart the Apache HTTP Server and PCP to begin data collection:
 +
 ----
diff --git a/guides/doc-Monitoring_Guide/topics/proc_installing-pcp-packages.adoc b/guides/doc-Monitoring_Guide/topics/proc_installing-pcp-packages.adoc
index 6f6d355..de3a185 100644
--- a/guides/doc-Monitoring_Guide/topics/proc_installing-pcp-packages.adoc
+++ b/guides/doc-Monitoring_Guide/topics/proc_installing-pcp-packages.adoc
@@ -9,7 +9,8 @@ This procedure describes how to install the PCP packages.
 +
 The default PCP data retention policy is to retain only that data collected during the past 14 days. Data storage per day is estimated to use usually between 100 MB and 500 MB of disk space, but may use up to several gigabytes.
 
-* Ensure that the base system on which Satellite Server is running is Red{nbsp}Hat Enterprise Linux 7.6. or later. The minimum supported version for the PCP packages is PCP version 4.1.
+* Ensure that the base system on which Satellite Server is running is Red{nbsp}Hat Enterprise Linux 7.6. or later.
+* The minimum supported version for the PCP packages is PCP version 5.0.
 
 .Procedure
 
@@ -23,6 +24,7 @@ The default PCP data retention policy is to retain only that data collected duri
 +
 ----
 # yum install pcp \
+  pcp-pmda-statsd \
   pcp-pmda-apache \
   pcp-pmda-postgresql \
   pcp-system-tools \
diff --git a/guides/doc-Monitoring_Guide/topics/proc_verifying-pcp-configuration.adoc b/guides/doc-Monitoring_Guide/topics/proc_verifying-pcp-configuration.adoc
index 82f7a86..cdbd9e7 100644
--- a/guides/doc-Monitoring_Guide/topics/proc_verifying-pcp-configuration.adoc
+++ b/guides/doc-Monitoring_Guide/topics/proc_verifying-pcp-configuration.adoc
@@ -18,8 +18,8 @@ Performance Co-Pilot configuration on satellite.example.com:
  timezone: AEST-10
  services: pmcd pmwebd
      pmcd: Version 3.12.2-1, 9 agents, 1 client
-     pmda: root pmcd proc xfs linux apache mmv postgresql jbd2
+     pmda: root pmcd proc xfs linux apache statsd postgresql jbd2
  pmlogger: primary logger: /var/log/pcp/pmlogger/satellite.example.com/20180802.00.10
 ----
 
-In this example, both the Performance Metrics Collector Daemon (pmcd), and the Performance Metrics Web Daemon (pmwebd) services are running. It also confirms the PMDAs which are collecting metrics. Finally, it lists the currently actively archive file, in which `pmlogger` is storing metrics.
\ No newline at end of file
+In this example, both the Performance Metrics Collector Daemon (pmcd), and the Performance Metrics Web Daemon (pmwebd) services are running. It also confirms the PMDAs which are collecting metrics. Finally, it lists the currently actively archive file, in which `pmlogger` is storing metrics.

Satellite docs is not building at all

[mcorr@mcorr doc-Provisioning_Guide]$ make Build=satellite
asciidoctor -a build=foreman -b xhtml5 -d book -o ../build/doc-Provisioning_Guide/index-foreman.html master.adoc

Any idea what's happening?

I did a make clean and cannot build any Satellite file.

Attributes not rendering properly in code examples

I noticed this while working on the VMware content. On preview, the attributes are visible rather than the values.

I can see it throughout the Libvirt chapter also.

Any idea why this isn't working?

Explain DHCP options

We should explain this a bit more in the prov guide:

https://community.theforeman.org/t/foreman-and-dhcp-options-explained/15127

HTTP boot installer remark

Once we get there (I think this is still undocumented) we need to make sure these params are present:

foreman-installer --foreman-proxy-httpboot=true --foreman-proxy-http=true --foreman-proxy-httpboot-listen-on=both

Integrate 3.1.5 Discovery image kernel options

Into provisioning guide from https://theforeman.org/plugins/foreman_discovery/15.0/index.html

Integrate 6.1 Troubleshooting into prov guide

Into provisioning guide from https://theforeman.org/plugins/foreman_discovery/15.0/index.html

Extract provisioning prerequisites

These bullets are very often same (installation media, activation keys), maybe it is worth extracting them into a separate adoc file and including it everywhere.

Look into improving this sentence of all provisioning procedures

@lzap commented the following on this line that exists in all provisioning procedures:

. Ensure that {ProjectServer} automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.

The problem is with this step which is used 3-4 times in this guide: Ensure that {ProjectServer} automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
It tells you to check something that Satellite always does. It's useless, but more than that - at this point we should be providing important information about NICs. What I would like to tell the user at this point:
Create all NICs you want Foreman to create, these are marked with the managed flag
Pick a primary interface (the flag), primary has the default route. Only one interface can be set as primary.
Pick a provision interface (the flag), it's MAC address is used to identify the system when PXE-booting or booting via bootdisk. Only one interface can be set as provision.
https://guides.github.com/features/mastering-markdown/
Can you suggest some wording? Is it worth extracting this into some kind of "module" and use it 3-4 times in this document?

Add info about monitoring to an external PCP instance

After we migrate Monitoring Guide this must be the very first change. We want to allow PCP running on RHEL7 to send data over network to PCP running on RHEL8 to leverage modern Grafana visualization software.

Replace Infoblox_hostname with infoblox_hostname

I hate hostname Infoblox_hostname I vote for changing this to simply infoblox-host. Issues:

• hostnames should always be lowercase
• dashes preferred over underscore
• it is a host not hostname

Debian/Ubuntu install guides contain not working scenarios

@ekohl noticed that Installing on Ubunthu/Debian guides contain scenarios that do not work on those OSes. Here is his feedback:

• http://docs.theforeman.org/guides/build/doc-Installing_Proxy_on_Debian/index-foreman-deb.html#configuring-capsule-default-certificate_smart-proxy
  Section 2.5. Configuring Smart Proxy server with a Default SSL Certificate in the Installing an External Smart Proxy Server on Debian guide does not work because the foreman-proxy-certs-generate command does not exist on Debian. All other sections that describe how to configure Foreman and Proxy with certificates do not work as well and require reworking.
• http://docs.theforeman.org/guides/build/doc-Installing_Proxy_on_Debian/index-foreman-deb.html#configuring-dns-dhcp-and-tftp_smart-proxy
  Rather than editing the service, you should really use --foreman-proxy-dhcp-interface and --foreman-proxy-dhcp-additional-interfaces. So pass --foreman-proxy-dhcp-additional-interfaces eth1 --foreman-proxy-dhcp-additional-interfaces eth2 in the procedure, drop 'Adding Multihomed DHCP details' entirely
• http://docs.theforeman.org/guides/build/doc-Installing_Proxy_on_Debian/index-foreman-deb.html#installing-capsule-server-packages_smart-proxy
  This section is also incorrect - you don't install a meta package, just the installer and the installer does everything
  so: apt-get install foreman-installe
• btw, the DHCP suggetion is also correct for Red Hat based instructions, both upstream and downstream

Add multiple subnets docs

We need to add this to install guides:

https://theforeman.org/plugins/katello/3.11/installation/index.html#multiple-subnets-and-domains

Fix all links

We have several types of links:

• link:/html/content_management_guide/importing_red_hat_content#Importing_Red_Hat_Content-Synchronizing_Red_Hat_Repositories[Synchronizing Red Hat Repositories] (converted by upstreamize)
• https://access.redhat.com/documentation/en-us/red_hat_satellite/6.4/html/installing_satellite_server_from_a_connected_network/preparing_your_environment_for_installation#ports_prerequisites[Port and Firewall Requirements]

We should convert all links that link content across guides to something like:

{base_url}/html/installing_satellite_server_from_a_connected_network/preparing_your_environment_for_installation#ports_prerequisites[Port and Firewall Requirements]

Where base_url is a variable:

:base_url: https://access.redhat.com/documentation/en-us/red_hat_satellite/{ProductVersion}

It will be different for foreman and satellite of course.

External links to RHEL (and other) docs are correct: https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Virtualization_Getting_Started_Guide/index.html[Red Hat Enterprise Linux 7 Virtualization Getting Started Guide] and they should be kept as-is.

Debian installation docs mention Katello requirements

https://docs.theforeman.org/guides/build/doc-Installing_Capsule_Server/index-foreman-deb.html lists some services that are not relevant.

• postgres
  On EL7 this is because of Pulpcore (Pulp 3), not relevant on Debian
• mongodb
  On EL7 this is because of Pulp 2, not relevant on Debian
• apache
  On EL7 this is because of a reverse proxy setup for RHSM, not relevant on Debian
• tomcat
  This isn't true for any capsule and in particular not for Debian. Tomcat is only used for Candlepin
• foreman
  This isn't true for any capsule
• foreman-proxy
  This one is true :)
• qpidd
  On EL7 this is because of Pulp 2, not relevant on Debian
• qdrouterd
  On EL7 this is because of Pulp 2, not relevant on Debian
• squid
  On EL7 this is because of Pulp 2, not relevant on Debian
• puppet
  This is optional on any setup, but currently installed by default in every scenario. If you want to be precise, we have both puppet and puppetserver processes.

Use the correct installer options for additional DHCP interfaces

https://github.com/theforeman/foreman-documentation/blob/master/guides/common/modules/proc_configuring-dns-dhcp-and-tftp.adoc suggests to edit /etc/systemd/system/dhcpd.service.d/interfaces.conf manually, but this is not needed. It's needlessly OS specific and the installer option --foreman-proxy-dhcp-additional-interfaces eth1 --foreman-proxy-dhcp-additional-interfaces eth2

We need another attribute for example FQDN in the doc

Hey,

I was reviewing the html version of the Foreman guide and see throughout

satellite.example.com

This is the standard we use in all the Satellite docs for a Fully Qualified Domain name that the user needs to substitute for their FQDN when they follow the instructions.

It should render in the code examples for Foreman as

foreman.example.com

Change wording in Load Balanced configuration to quantify support for Provisioning

https://bugzilla.redhat.com/show_bug.cgi?id=1865846
"Provisioning hosts is not supported in the Satellite load-balanced setup." The previous statement does not make it clear that provisioning/virt-who or other content is supported to be installed on the individual capsules that are load balanced but not the HA itself.

Suggestions for improvement:
The Load Balanced setup offers high availability for the simple content access (Yum, Puppet), other services running on the individual capsules such as provisioning, virt-who etc should not be accessed through the Load Balancer but can be accessed directly from the Capsule.

Integrate 5.4 Running arbitrary commands after boot

Into provisioning guide from https://theforeman.org/plugins/foreman_discovery/15.0/index.html

Break app_create_images.adoc into modular parts

We currently hide this little bit irrelevant appendix. Let's break it into modules:

• rhel6
• rhel7
• fedora

And assembly those accordingly.

Disconnected installation

We have removed disconnected procedure because upstream it is very different.

Now we have a tutorial for upstream, we could incorporate this into docs:

https://community.theforeman.org/t/installing-foreman-in-an-air-gapped-environment/18518

Better book titles upstream

On our front page we currently have:

• Installing Foreman on RHEL/CentOS
• Installing Smart Proxy on RHEL/CentOS
• Installing Foreman on Debian/Ubuntu
• Installing Smart Proxy on Debian/Ubuntu

https://docs.theforeman.org/web/

But when you open these it reads e.g. "Installing Foreman server from a Connected Network". We should probably change these titles to match the front page or come up with something that works fine.

Dynamic parititioning scheme

I've noticed that we have an undocumented feature (surprise!): dynamic partitioning scheme. Since Foreman does not ship with any dynamic partitioning scheme, I've decided to file a PR to include one with the following explanation:

When a partition template contains line starting with "#Dynamic", the contents will be put into %pre shell scriplet rather and it's expected it creates a file "/tmp/diskpart.cfg" which is then included into the Kickstart partitioning section. This allows generating parititioning scheme on the managed node befure
Anaconda starts installation.

This template is an example of such dynamic partitioning scheme. It follows recommended scheme of Red Hat Enterprise Linux for servers (no extra allocation for hibernation):

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-swapspace

#Dynamic (do not remove this line)

MEMORY=$((`grep MemTotal: /proc/meminfo | sed 's/^MemTotal: *//'|sed 's/ .*//'` / 1024))
if [ "$MEMORY" -lt 2048 ]; then
    SWAP_MEMORY=$(($MEMORY * 2))
elif [ "$MEMORY" -lt 8192 ]; then
    SWAP_MEMORY=$MEMORY
elif [ "$MEMORY" -lt 65536 ]; then
    SWAP_MEMORY=$(($MEMORY / 2))
else
    SWAP_MEMORY=32768
fi

cat <<EOF > /tmp/diskpart.cfg
zerombr yes
clearpart --all --initlabel
part /boot --fstype ext4 --size 200 --asprimary
part swap --size "$SWAP_MEMORY"
part / --fstype ext4 --size 1024 --grow
EOF

The PR is here: theforeman/community-templates#672

Wrong output/url after executing "make BUILD=satellite" command

After executing make BUILD=satellite, satellite's attributes are not getting substituted in the index.html

Add docs for DHCP maintainaince rake task

There will be new command that allows synchronizing of DHCP records between Foreman database and DHCP smart proxy. I fail to find a good place for this, I was thinking Provisioning Guide appendix but it does not feel right. Thus creating a ticket to decide. It's short, mostly it's documented in its help text:

https://github.com/theforeman/foreman/pull/7073/files

Create a generator for installer options

Our installer options table on official site is generated:

https://theforeman.org/manuals/1.23/index.html#3.2.2InstallerOptions

We must do the same for adoc format (as an appendix perhaps):

https://github.com/theforeman/theforeman.org/blob/gh-pages/scripts/installer/installer-enable-to-table

Broken xref in Managing Hosts guide

https://docs.theforeman.org/master/Managing_Hosts/index-foreman.html#sect-Red_Hat_Satellite-Managing_Hosts-Adding_a_Host_to_a_Host_Collection

I will try fix it this week

Document Registering Hosts upstream

The Registering Hosts section that is available downstream is hidden upstream because of information about subscriptions that is irrelevant upstream.
From @lzap :

Technically, all of this would actually work but there's confusing amount of info about subscriptions etc. It makes sense to someone familiar with Satellite, but random upstream user would be only confused.

It is required to review the section and make it usable upstream too.

Errata management guide link broken

URL        `https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7-beta/html/errata_management_guide/'
Name       `Errata Management'
Parent URL file:///home/lzap/work/foreman-documentation/guides/build/doc-Installing_Foreman_on_Debian/index-foreman.html, line 3305, col 4
Real URL   https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7-beta/html/errata_management_guide/
Check time 3.376 seconds
Result     Error: 404 Not Found

We should not be merging any PR which has red validation tests. Master is currently broken, there are more of these.

Satellite Versions appearing as Foreman in Managing Hosts guide

http://docs.theforeman.org/guides/build/doc-Managing_Hosts/index-foreman.html#chap-Red_Hat_Satellite-Managing_Hosts-Integrating_Satellite_and_Ansible_Tower

Will fix later.

Compute Resource Prerequisites

I am currently working on the Amazon EC2 topic and ran into something I don't know the answer to from a Foreman perspective.

I checked had Rahul done anything with this in the VMware file he was working on, and he had not dealt with it either. We will have to deal with this for every compute resource and every new compute resource that we add, so we need to figure it out.

For example

If you check the prerequisites:

for https://github.com/theforeman/foreman-documentation/blob/aabd67903a49da47722be7ef4be7bd3523447441/guides/doc-Provisioning_Guide/topics/Virt-VMWare.adoc

It is similar to the https://github.com/theforeman/foreman-documentation/blob/aabd67903a49da47722be7ef4be7bd3523447441/guides/doc-Provisioning_Guide/topics/Cloud-Amazon_EC2.adoc that I'm working on.

Prerequisites for Amazon EC2 Provisioning

The requirements for Amazon EC2 provisioning include:

Synchronized content repositories for Red Hat Enterprise Linux 7. For more information, see Synchronizing Red Hat Repositories in the Content Management Guide.

A {SmartProxyServer} managing a network in your EC2 environment. Use a Virtual Private Cloud (VPC) to ensure a secure network between the hosts and the {SmartProxyServer}.

An Amazon Machine Image (AMI) for image-based provisioning.

An activation key for host registration. For more information, see Creating An Activation Key in the Content Management guide.

In Foreman, what replaces the content repos? Uploading an image?
In Foreman for host registration, what do they do in place of activation keys? I can add an ifeval to say this is only available with Katello, but should I just have nothing for Foreman host registration there?

Would appreciate any help.

Update hammer command in for vmware create

As per this change:

https://bugzilla.redhat.com/show_bug.cgi?id=1758530

Custom content should not be referred to as custom upstream

In https://community.theforeman.org/t/howto-for-own-rpms-on-foreman-katello/18577/7 points out, very validly how custom content is probably all content in the upstream that is not Red Hat, and the custom is a term that doesn't add value upstream.

I would suggest introducing an attribute to refer to it either simply as 'content' or 'non-Red Hat content'.

Some of the wording might need to be refined with ifevals to speak to the particular context of upstream content rather than downstream Satellite.

Document efibootmgr_netboot

Foreman workflow is based on setting all managed servers to boot from network and then from HDD, therefore Foreman can decide if to reinstall OS or exit PXE and boot from secondary device (HDD). But in EFI world, this does not work reliably - OS installer usually creates a new EFI entry as the first, so after restart the server boots into the new system. The issue is reprovisioning - when the host is put into build mode in Foreman and the server is restarted, it will ignore this and boot into the old system.

The solution is to modify EFI boot order back to boot from previous entry, assuming that the first entry was PXE/iPXE. There is a proposal snippet 25 included from provisioning template, but since this does not work reliably (e.g. in libvirt this fails) the proposed solution is opt-it only via “efi_bootentry” host parameter:

When set to “previous” after OS installation the new entry will be removed from top and appended as the last entry.
When set to arbitrary text, this will be used as input to “grep -E” as a regular expression to find boot entry to set as the first. Every EFI firmware vendor names PXE/HTTP Boot entries differently, so there is no standard and a regular expression for all hosts must be created unfortunately.
No action is taken when not set (host will boot from HDD everytime).

https://community.theforeman.org/t/discovery-ipxe-efi-workflow-in-foreman-1-20/13026

We should describe this in docs. This is a common issue across all UEFI provisioning workflows and the snippet should help users to workaround the problem.

https://github.com/theforeman/community-templates/pull/557/files

Update Kickstart options upstream

https://bugzilla.redhat.com/show_bug.cgi?id=1757152

Iron out eth1 in the Networking chapter (4)

The chapter tells to use eth1 for nameserver however I don't see a reason to do so. Actually we recommend to deploy Satellite on a single NIC hosts, that is the very opposite. Need to fix this.

Add info about expected interface names

Foreman expects network devices to follow some naming scheme in order to detect them correctly. For example if bond is named "mybond0" it will not be correctly detected and host registration (through puppet, ansible or rhsm) will fail. It must be named "bondN" where N is a number. Similar rules apply for others. We need to out this into some guide.

Describe new dynflow scaling (2.1)

theforeman/theforeman.org#1592

baseURL parameter not fulfilling upstream requirements - how to handle URLS

Hi,

The http://docs.theforeman.org/guides/build/doc-Deploying_on_AWS/index-foreman.html#_use_cases_known_to_work section has links only to Satellite docs, when all these doc links are now upstream.

Please add an equivalent.

Update attribute for foreman-maintain/satellite-maintain

As part of this bug:

https://bugzilla.redhat.com/show_bug.cgi?id=1759615

Upstreamize.rb need foreman-maintain and foreman-installer

In PR #86 I noticed that the Upstreamize.rb script did not catch
As part of that PR, I've added satellite-maintain as an attribute.
Let's add them to the file for future use.

Adding a note to Bare_Metal.adocs

@lzap suggested as part of PR #42
adding to line 60:

NOTE: PXE workflows can be used to provision virtual machines which are not under {Project} control as well."

moving here for later discussion

Rewrite FIPS chapter in Provisioning Guide

FIPS templates have been merged into community-templates repo and are now part of Foreman. They are under different name now:

https://github.com/theforeman/community-templates/pull/560/files

Remove Satellite word from directory name

I think we should not use either Foreman or Satellite in directory names: doc-Installing_Satellite_Server_Disconnected. They are mapped to URLs and also information value is zero, the shorter URL the better.

doc-Content_Management_Guide
doc-Deploying_on_AWS
doc-Installing_Proxy_on_Debian
doc-Installing_Proxy_on_Red_Hat
doc-Installing_Satellite_Server_Disconnected
doc-Installing_Server_on_Debian
doc-Installing_Server_on_Red_Hat
doc-Managing_Hosts
doc-Provisioning_Guide

In general, we should keep them as short as possible regardless of the actual book title. If you can identify and set up some naming rules, go ahead and put this into the README. @spetrosi @melcorr @tahliar