Document how to setup external OpenVox server for Smart Proxy

guides/common/modules/con_using-external-openvox-servers.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="using-external-openvox-servers"]
+= Using external OpenVox servers
+
+[role="_abstract"]
+{Project} supports using external OpenVox servers that send reports and facts to {ProjectServer} through {SmartProxies}.
+To forward port {smartproxy_port} from {SmartProxies} to port 443 on {ProjectServer}, you must enable the Request Forwarder plugin on your {SmartProxyServers}.
+
+[IMPORTANT]
+====
+Hosts will only send reports and facts to {Project}.
+You cannot override the Puppet classes, Puppet environment, and Puppet smart class parameters of your hosts.
+
+If you provision hosts through {Project}, you cannot directly attach them to your external OpenVox server.
+Leave the Puppet Proxy and Puppet CA Proxy empty during host provisioning.
+
+Instead, use the certificates of your existing OpenVox infrastructure.
+====

guides/common/modules/proc_attaching-smart-proxy-to-external-openvox-server.adoc

@@ -0,0 +1,95 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="attaching-{smart-proxy-context}-to-external-openvox-server"]
+= Attaching {SmartProxy} to external OpenVox server
+
+[role="_abstract"]
+You can attach an external OpenVox server to {SmartProxies}.
+
+.Prerequisites
+* You have enabled the Puppet plugin on your {ProjectServer}.
+For more information, see xref:enabling-puppet-integration-with-{project-context}[].
+* You have enabled the Request Forwarder plugin on your {ProjectServer}.
+For more information, see xref:installing-the-request-forwarder-plugin[].
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Administer* > *Settings*.
+. On the *Authentication* tab, locate the *Trusted hosts* setting and add the FQDN of your OpenVox server to the list.
+. On your {SmartProxyServer}, extend the list of trusted hosts with your OpenVox server in `/etc/foreman-installer/scenarios.d/foreman-proxy-content-answers.yaml`:
++
+[source, yaml, options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+foreman_proxy:
+  trusted_hosts:
+  - _My_{Project}_Server_FQDN_
+  - _My_{SmartProxy}_Server_FQDN_
+  - _My_OpenVox_Server_FQDN_
+----
+. Install OpenVox or Puppet server.
++
+For more information, see https://voxpupuli.org/openvox/install/[Installing OpenVox].
+. On your {ProjectServer}, create certificates for your OpenVox server:
+** If you use self-signed certificates:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {certs-generate} \
+--certs-tar _My_Certificates_Archive_ \
+--foreman-proxy-fqdn _My_OpenVox_Server_FQDN_ \
+--node-fqdn _My_OpenVox_Server_FQDN_
+----
+** If you use custom certificates:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {certs-generate} \
+--certs-tar _My_Certificates_Archive_ \
+--foreman-proxy-fqdn _My_OpenVox_Server_FQDN_ \
+--node-fqdn _My_OpenVox_Server_FQDN_ \
+--server-ca-cert _My_CA_Cert_ \
+--server-cert _My_Cert_ \
+--server-key _My_Key_
+----
+. From your {ProjectServer}, transfer the certificates to your OpenVox server:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# scp /root/_My_Certificates_Archive_ root@openvox.example.com:/root/
+----
+. On your OpenVox server, extract the certificates:
++
+----
+# tar xf /root/_My_Certificates_Archive_
+----
+. On your OpenVox server, configure the connection to your {Project} in `/etc/puppetlabs/puppet/foreman.yaml`:
++
+[source, yaml, options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+:url: "https://{smartproxy-example-com}:{smartproxy_port}"
+:ssl_ca: "/path/to/katello-server-ca.crt"
+:ssl_cert: "/path/to/puppet-client.crt"
+:ssl_key: "/path/puto/puppet-client.key"
+
+:puppetdir: "/opt/puppetlabs/server/data/puppetserver"
+:puppetuser: "puppet"
+:facts: true
+:timeout: 10
+:threads: null
+----
+. From your {ProjectServer}, copy the `report.rb` script to your OpenVox server:
++
+----
+# scp /usr/share/foreman-installer/modules/puppetserver_foreman/files/report.rb root@openvox.example.com:/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/reports/foreman.rb
+----
+. Configure your OpenVox server to upload reports:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# puppet config set --section main reports "foreman"
+----
+. Restart your OpenVox server:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# systemctl restart puppetserver.service
+----

guides/common/modules/proc_installing-the-request-forwarder-plugin.adoc

@@ -0,0 +1,49 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="installing-the-request-forwarder-plugin"]
+= Installing the Request Forwarder plugin
+
+[role="_abstract"]
+If you use port 8443 on {SmartProxyServer} to upload Puppet reports and host facts from hosts to {ProjectServer}, install the Request Forwarder plugin on your {SmartProxyServer}.
+Afterwards, configure your OpenVox server to use the new API endpoint of your {SmartProxyServers}.
+
+.Procedure
+. Install the plugin on your {SmartProxyServer}:
++
+[options="nowrap", subs="verbatim,quotes,attributes"]
+----
+# {project-package-install} rubygem-smart_proxy_request_forwarder
+----
+. Enable the plugin:
++
+[options="nowrap", subs="verbatim,quotes,attributes"]
+----
+# cat > /etc/foreman-proxy/settings.d/request_forwarder.yml << EOF
+---
+:enabled: https
+EOF
+----
+. Configure your {SmartProxyServer}:
++
+[options="nowrap", subs="verbatim,quotes,attributes"]
+----
+# {foreman-installer}
+----
+. Restart {Project} services:
++
+[options="nowrap", subs="verbatim,quotes,attributes"]
+----
+# {foreman-maintain} service restart --only foreman-proxy
+----
+. On your OpenVox server, replace the URL in `/etc/puppetlabs/puppet/foreman.yaml`:
++
+[source, yaml, options="nowrap", subs="verbatim,quotes,attributes"]
+----
+:url: "https://{smartproxy-example-com}:{smartproxy_port}/"
+----
+. Restart the OpenVox service:
++
+[options="nowrap", subs="verbatim,quotes,attributes"]
+----
+# systemctl restart puppetserver
+----

guides/doc-Managing_Configurations_Puppet/master.adoc

@@ -23,6 +23,14 @@ include::common/modules/con_enabling-puppet-integration-with-project.adoc[levelo
 
 include::common/modules/proc_installing-puppet-server-on-projectserver-and-smartproxyservers.adoc[leveloffset=+2]
 
+ifdef::katello,orcharhino[]
+include::common/modules/con_using-external-openvox-servers.adoc[leveloffset=+2]
+
+include::common/modules/proc_installing-the-request-forwarder-plugin.adoc[leveloffset=+2]
+
+include::common/modules/proc_attaching-smart-proxy-to-external-openvox-server.adoc[leveloffset=+2]
+endif::[]
+
 include::common/modules/proc_installing-and-configuring-puppet-agent-during-host-provisioning.adoc[leveloffset=+2]
 
 include::common/modules/proc_installing-and-configuring-puppet-agent-during-host-registration.adoc[leveloffset=+2]