From a40296488bedda00d7d1229fb221303c59eba54b Mon Sep 17 00:00:00 2001 From: Cole Higgins Date: Fri, 16 Aug 2024 13:22:26 -0400 Subject: [PATCH 1/4] Add 3.12 folder and update nightly --- _config.yml | 1 + _includes/manuals/3.12/1.1_architecture.md | 17 + _includes/manuals/3.12/1.2_release_notes.md | 19 + .../3.12/2.1_quickstart_installation.md | 193 ++ .../manuals/3.12/2.2_quickstart_puppet.md | 39 + _includes/manuals/3.12/2_quickstart_guide.md | 18 + .../manuals/3.12/3.1.1_supported_platforms.md | 41 + .../3.12/3.1.2_hardware_requirements.md | 18 + .../manuals/3.12/3.1.3_puppet_versions.md | 45 + .../3.12/3.1.4_browser_compatibility.md | 12 + .../3.12/3.1.5_firewall_configuration.md | 56 + .../manuals/3.12/3.1_system_requirements.md | 1 + _includes/manuals/3.12/3.2.1_installation.md | 21 + .../manuals/3.12/3.2.2_installer_options.md | 2547 +++++++++++++++++ .../3.12/3.2.3_installation_scenarios.md | 192 ++ .../manuals/3.12/3.2_foreman_installer.md | 22 + _includes/manuals/3.12/3.3.1_rpm_packages.md | 66 + .../manuals/3.12/3.3.2_debian_packages.md | 102 + .../manuals/3.12/3.3_install_from_packages.md | 4 + .../manuals/3.12/3.4_install_from_source.md | 81 + _includes/manuals/3.12/3.5.1_initial_setup.md | 42 + .../3.12/3.5.2_configuration_options.md | 486 ++++ .../manuals/3.12/3.5.3_database_setup.md | 18 + .../manuals/3.12/3.5.4_puppet_reports.md | 82 + .../manuals/3.12/3.5.5_facts_and_the_enc.md | 156 + _includes/manuals/3.12/3.5.6_cli.md | 52 + _includes/manuals/3.12/3.5_configuration.md | 3 + _includes/manuals/3.12/3.6_upgrade.md | 227 ++ .../manuals/3.12/3_installing_foreman.md | 3 + .../manuals/3.12/4.1.1_authentication.md | 241 ++ .../3.12/4.1.2_roles_and_permissions.md | 158 + _includes/manuals/3.12/4.1.3_trends.md | 5 + _includes/manuals/3.12/4.1.4_auditing.md | 57 + _includes/manuals/3.12/4.1.5_searching.md | 76 + .../manuals/3.12/4.1.6_user_management.md | 7 + .../manuals/3.12/4.10.1_global_status.md | 23 + _includes/manuals/3.12/4.10.2_substatuses.md | 60 + .../3.12/4.10.3_searching_by_statuses.md | 24 + _includes/manuals/3.12/4.10_monitoring.md | 5 + .../manuals/3.12/4.11.1_report_templates.md | 27 + _includes/manuals/3.12/4.11.2_macros.md | 26 + _includes/manuals/3.12/4.11_reports.md | 6 + _includes/manuals/3.12/4.2.1_puppet_envs.md | 30 + .../manuals/3.12/4.2.2_puppet_classes.md | 130 + _includes/manuals/3.12/4.2.3_puppet_params.md | 61 + _includes/manuals/3.12/4.2.4_param_classes.md | 94 + _includes/manuals/3.12/4.2.5_matchers.md | 270 ++ _includes/manuals/3.12/4.2_managing_puppet.md | 2 + .../manuals/3.12/4.3.10_smartproxy_ssl.md | 71 + .../manuals/3.12/4.3.11_smartproxy_libvirt.md | 114 + .../3.12/4.3.12_smartproxy_templates.md | 21 + .../manuals/3.12/4.3.13_smartproxy_logs.md | 11 + .../3.12/4.3.1_smartproxy_installation.md | 105 + .../manuals/3.12/4.3.2_smartproxy_settings.md | 125 + .../3.12/4.3.3.1_smartproxy_bmc_ssh.md | 20 + .../manuals/3.12/4.3.3_smartproxy_bmc.md | 16 + _includes/manuals/3.12/4.3.4.2_isc_dhcp.md | 77 + _includes/manuals/3.12/4.3.4.3_ms_dhcp.md | 26 + .../manuals/3.12/4.3.4_smartproxy_dhcp.md | 109 + _includes/manuals/3.12/4.3.5.2_bind.md | 37 + _includes/manuals/3.12/4.3.5.3_gsstsig.md | 81 + .../manuals/3.12/4.3.5_smartproxy_dns.md | 110 + .../manuals/3.12/4.3.6_smartproxy_puppet.md | 56 + .../manuals/3.12/4.3.7_smartproxy_puppetca.md | 121 + .../manuals/3.12/4.3.8.2_freeipa_realm.md | 87 + .../manuals/3.12/4.3.8_smartproxy_realm.md | 21 + .../manuals/3.12/4.3.9_smartproxy_tftp.md | 81 + _includes/manuals/3.12/4.3_smartproxy.md | 25 + _includes/manuals/3.12/4.4.1_prov_os.md | 14 + _includes/manuals/3.12/4.4.2_prov_media.md | 14 + .../manuals/3.12/4.4.3_prov_templates.md | 103 + _includes/manuals/3.12/4.4.4_prov_archs.md | 6 + _includes/manuals/3.12/4.4.4_prov_ptables.md | 170 ++ _includes/manuals/3.12/4.4.6_prov_workflow.md | 73 + .../manuals/3.12/4.4.7_prov_networking.md | 39 + .../manuals/3.12/4.4.8.1_prov_freebsd.md | 23 + _includes/manuals/3.12/4.4.8.2_prov_sles.md | 4 + .../manuals/3.12/4.4.8.3_prov_windows.md | 183 ++ _includes/manuals/3.12/4.4.8_prov_os_notes.md | 1 + _includes/manuals/3.12/4.4_provisioning.md | 2 + _includes/manuals/3.12/4.5.1_cli_examples.md | 89 + _includes/manuals/3.12/4.5.2_cli_success.md | 86 + _includes/manuals/3.12/4.5_cli.md | 1 + .../manuals/3.12/4.6.1_email_preferences.md | 14 + _includes/manuals/3.12/4.6.2_email_account.md | 4 + _includes/manuals/3.12/4.6.3_email_host.md | 8 + .../manuals/3.12/4.6.4_email_scheduled.md | 8 + _includes/manuals/3.12/4.6_email.md | 6 + .../manuals/3.12/4.7_managing_ansible.md | 1 + _includes/manuals/3.12/4.8_managing_chef.md | 1 + _includes/manuals/3.12/4.9_managing_salt.md | 1 + _includes/manuals/3.12/4_general_foreman.md | 2 + .../manuals/3.12/5.1.10_apipie-bindings.md | 101 + _includes/manuals/3.12/5.1.11_graphql.md | 69 + .../manuals/3.12/5.1.12_dynflow_scaling.md | 172 ++ .../manuals/3.12/5.1.1_request_examples.md | 77 + .../3.12/5.1.2_api_json_collections.md | 55 + .../3.12/5.1.3_api_json_single_objects.md | 12 + _includes/manuals/3.12/5.1.4_api_customize.md | 70 + .../manuals/3.12/5.1.5_nested_api_routes.md | 11 + _includes/manuals/3.12/5.1.6_versioning.md | 9 + _includes/manuals/3.12/5.1.7_associations.md | 47 + .../manuals/3.12/5.1.8_authentication.md | 39 + _includes/manuals/3.12/5.1.9_oauth.md | 34 + _includes/manuals/3.12/5.1_api.md | 3 + _includes/manuals/3.12/5.2.1_cr_using.md | 22 + _includes/manuals/3.12/5.2.2_cr_profiles.md | 78 + _includes/manuals/3.12/5.2.3_cr_ec2.md | 13 + _includes/manuals/3.12/5.2.4_cr_gce.md | 48 + _includes/manuals/3.12/5.2.5_cr_libvirt.md | 76 + _includes/manuals/3.12/5.2.6_cr_openstack.md | 13 + _includes/manuals/3.12/5.2.7_cr_ovirt.md | 44 + _includes/manuals/3.12/5.2.8_cr_vmware.md | 102 + .../manuals/3.12/5.2.9_cr_encryption_key.md | 9 + .../manuals/3.12/5.2_compute_resources.md | 74 + .../manuals/3.12/5.4.1_comms_puppetserver.md | 67 + _includes/manuals/3.12/5.4.2_comms_proxy.md | 53 + _includes/manuals/3.12/5.4_communications.md | 2 + _includes/manuals/3.12/5.5.1_backup.md | 38 + _includes/manuals/3.12/5.5.2_recovery.md | 74 + .../manuals/3.12/5.5_backup_and_recovery.md | 13 + _includes/manuals/3.12/5.6_rails_console.md | 41 + .../manuals/3.12/5.7.1_quick_configuration.md | 24 + _includes/manuals/3.12/5.7.2_HBAC_rules.md | 28 + _includes/manuals/3.12/5.7.3_kerberos.md | 62 + .../manuals/3.12/5.7.4_pam_authentication.md | 20 + .../5.7.5_populate_users_attributes_groups.md | 57 + .../3.12/5.7.6_namespace_separation.md | 24 + _includes/manuals/3.12/5.7.7_openid_sso.md | 107 + .../3.12/5.7_external_authentication.md | 2 + _includes/manuals/3.12/5.8.1_database.md | 2 + _includes/manuals/3.12/5.8.2_encryption_rb.md | 2 + _includes/manuals/3.12/5.8.3_secret_token.md | 9 + .../3.12/5.8.4_other_considerations.md | 6 + .../manuals/3.12/5.8_multiple_foremen.md | 4 + _includes/manuals/3.12/5.9_http_proxy.md | 33 + _includes/manuals/3.12/6_plugins.md | 1 + _includes/manuals/3.12/7.1_novnc.md | 40 + _includes/manuals/3.12/7.2_debugging.md | 213 ++ _includes/manuals/3.12/7.3_getting_help.md | 32 + _includes/manuals/3.12/missing.html | 1 + manuals/3.12/index.md | 332 +++ manuals/3.12/quickstart_guide.md | 28 + manuals/nightly/index.md | 2 +- 144 files changed, 10527 insertions(+), 1 deletion(-) create mode 100644 _includes/manuals/3.12/1.1_architecture.md create mode 100644 _includes/manuals/3.12/1.2_release_notes.md create mode 100644 _includes/manuals/3.12/2.1_quickstart_installation.md create mode 100644 _includes/manuals/3.12/2.2_quickstart_puppet.md create mode 100644 _includes/manuals/3.12/2_quickstart_guide.md create mode 100644 _includes/manuals/3.12/3.1.1_supported_platforms.md create mode 100644 _includes/manuals/3.12/3.1.2_hardware_requirements.md create mode 100644 _includes/manuals/3.12/3.1.3_puppet_versions.md create mode 100644 _includes/manuals/3.12/3.1.4_browser_compatibility.md create mode 100644 _includes/manuals/3.12/3.1.5_firewall_configuration.md create mode 100644 _includes/manuals/3.12/3.1_system_requirements.md create mode 100644 _includes/manuals/3.12/3.2.1_installation.md create mode 100644 _includes/manuals/3.12/3.2.2_installer_options.md create mode 100644 _includes/manuals/3.12/3.2.3_installation_scenarios.md create mode 100644 _includes/manuals/3.12/3.2_foreman_installer.md create mode 100644 _includes/manuals/3.12/3.3.1_rpm_packages.md create mode 100644 _includes/manuals/3.12/3.3.2_debian_packages.md create mode 100644 _includes/manuals/3.12/3.3_install_from_packages.md create mode 100644 _includes/manuals/3.12/3.4_install_from_source.md create mode 100644 _includes/manuals/3.12/3.5.1_initial_setup.md create mode 100644 _includes/manuals/3.12/3.5.2_configuration_options.md create mode 100644 _includes/manuals/3.12/3.5.3_database_setup.md create mode 100644 _includes/manuals/3.12/3.5.4_puppet_reports.md create mode 100644 _includes/manuals/3.12/3.5.5_facts_and_the_enc.md create mode 100644 _includes/manuals/3.12/3.5.6_cli.md create mode 100644 _includes/manuals/3.12/3.5_configuration.md create mode 100644 _includes/manuals/3.12/3.6_upgrade.md create mode 100644 _includes/manuals/3.12/3_installing_foreman.md create mode 100644 _includes/manuals/3.12/4.1.1_authentication.md create mode 100644 _includes/manuals/3.12/4.1.2_roles_and_permissions.md create mode 100644 _includes/manuals/3.12/4.1.3_trends.md create mode 100644 _includes/manuals/3.12/4.1.4_auditing.md create mode 100644 _includes/manuals/3.12/4.1.5_searching.md create mode 100644 _includes/manuals/3.12/4.1.6_user_management.md create mode 100644 _includes/manuals/3.12/4.10.1_global_status.md create mode 100644 _includes/manuals/3.12/4.10.2_substatuses.md create mode 100644 _includes/manuals/3.12/4.10.3_searching_by_statuses.md create mode 100644 _includes/manuals/3.12/4.10_monitoring.md create mode 100644 _includes/manuals/3.12/4.11.1_report_templates.md create mode 100644 _includes/manuals/3.12/4.11.2_macros.md create mode 100644 _includes/manuals/3.12/4.11_reports.md create mode 100644 _includes/manuals/3.12/4.2.1_puppet_envs.md create mode 100644 _includes/manuals/3.12/4.2.2_puppet_classes.md create mode 100644 _includes/manuals/3.12/4.2.3_puppet_params.md create mode 100644 _includes/manuals/3.12/4.2.4_param_classes.md create mode 100644 _includes/manuals/3.12/4.2.5_matchers.md create mode 100644 _includes/manuals/3.12/4.2_managing_puppet.md create mode 100644 _includes/manuals/3.12/4.3.10_smartproxy_ssl.md create mode 100644 _includes/manuals/3.12/4.3.11_smartproxy_libvirt.md create mode 100644 _includes/manuals/3.12/4.3.12_smartproxy_templates.md create mode 100644 _includes/manuals/3.12/4.3.13_smartproxy_logs.md create mode 100644 _includes/manuals/3.12/4.3.1_smartproxy_installation.md create mode 100644 _includes/manuals/3.12/4.3.2_smartproxy_settings.md create mode 100644 _includes/manuals/3.12/4.3.3.1_smartproxy_bmc_ssh.md create mode 100644 _includes/manuals/3.12/4.3.3_smartproxy_bmc.md create mode 100644 _includes/manuals/3.12/4.3.4.2_isc_dhcp.md create mode 100644 _includes/manuals/3.12/4.3.4.3_ms_dhcp.md create mode 100644 _includes/manuals/3.12/4.3.4_smartproxy_dhcp.md create mode 100644 _includes/manuals/3.12/4.3.5.2_bind.md create mode 100644 _includes/manuals/3.12/4.3.5.3_gsstsig.md create mode 100644 _includes/manuals/3.12/4.3.5_smartproxy_dns.md create mode 100644 _includes/manuals/3.12/4.3.6_smartproxy_puppet.md create mode 100644 _includes/manuals/3.12/4.3.7_smartproxy_puppetca.md create mode 100644 _includes/manuals/3.12/4.3.8.2_freeipa_realm.md create mode 100644 _includes/manuals/3.12/4.3.8_smartproxy_realm.md create mode 100644 _includes/manuals/3.12/4.3.9_smartproxy_tftp.md create mode 100644 _includes/manuals/3.12/4.3_smartproxy.md create mode 100644 _includes/manuals/3.12/4.4.1_prov_os.md create mode 100644 _includes/manuals/3.12/4.4.2_prov_media.md create mode 100644 _includes/manuals/3.12/4.4.3_prov_templates.md create mode 100644 _includes/manuals/3.12/4.4.4_prov_archs.md create mode 100644 _includes/manuals/3.12/4.4.4_prov_ptables.md create mode 100644 _includes/manuals/3.12/4.4.6_prov_workflow.md create mode 100644 _includes/manuals/3.12/4.4.7_prov_networking.md create mode 100644 _includes/manuals/3.12/4.4.8.1_prov_freebsd.md create mode 100644 _includes/manuals/3.12/4.4.8.2_prov_sles.md create mode 100644 _includes/manuals/3.12/4.4.8.3_prov_windows.md create mode 100644 _includes/manuals/3.12/4.4.8_prov_os_notes.md create mode 100644 _includes/manuals/3.12/4.4_provisioning.md create mode 100644 _includes/manuals/3.12/4.5.1_cli_examples.md create mode 100644 _includes/manuals/3.12/4.5.2_cli_success.md create mode 100644 _includes/manuals/3.12/4.5_cli.md create mode 100644 _includes/manuals/3.12/4.6.1_email_preferences.md create mode 100644 _includes/manuals/3.12/4.6.2_email_account.md create mode 100644 _includes/manuals/3.12/4.6.3_email_host.md create mode 100644 _includes/manuals/3.12/4.6.4_email_scheduled.md create mode 100644 _includes/manuals/3.12/4.6_email.md create mode 100644 _includes/manuals/3.12/4.7_managing_ansible.md create mode 100644 _includes/manuals/3.12/4.8_managing_chef.md create mode 100644 _includes/manuals/3.12/4.9_managing_salt.md create mode 100644 _includes/manuals/3.12/4_general_foreman.md create mode 100644 _includes/manuals/3.12/5.1.10_apipie-bindings.md create mode 100644 _includes/manuals/3.12/5.1.11_graphql.md create mode 100644 _includes/manuals/3.12/5.1.12_dynflow_scaling.md create mode 100644 _includes/manuals/3.12/5.1.1_request_examples.md create mode 100644 _includes/manuals/3.12/5.1.2_api_json_collections.md create mode 100644 _includes/manuals/3.12/5.1.3_api_json_single_objects.md create mode 100644 _includes/manuals/3.12/5.1.4_api_customize.md create mode 100644 _includes/manuals/3.12/5.1.5_nested_api_routes.md create mode 100644 _includes/manuals/3.12/5.1.6_versioning.md create mode 100644 _includes/manuals/3.12/5.1.7_associations.md create mode 100644 _includes/manuals/3.12/5.1.8_authentication.md create mode 100644 _includes/manuals/3.12/5.1.9_oauth.md create mode 100644 _includes/manuals/3.12/5.1_api.md create mode 100644 _includes/manuals/3.12/5.2.1_cr_using.md create mode 100644 _includes/manuals/3.12/5.2.2_cr_profiles.md create mode 100644 _includes/manuals/3.12/5.2.3_cr_ec2.md create mode 100644 _includes/manuals/3.12/5.2.4_cr_gce.md create mode 100644 _includes/manuals/3.12/5.2.5_cr_libvirt.md create mode 100644 _includes/manuals/3.12/5.2.6_cr_openstack.md create mode 100644 _includes/manuals/3.12/5.2.7_cr_ovirt.md create mode 100644 _includes/manuals/3.12/5.2.8_cr_vmware.md create mode 100644 _includes/manuals/3.12/5.2.9_cr_encryption_key.md create mode 100644 _includes/manuals/3.12/5.2_compute_resources.md create mode 100644 _includes/manuals/3.12/5.4.1_comms_puppetserver.md create mode 100644 _includes/manuals/3.12/5.4.2_comms_proxy.md create mode 100644 _includes/manuals/3.12/5.4_communications.md create mode 100644 _includes/manuals/3.12/5.5.1_backup.md create mode 100644 _includes/manuals/3.12/5.5.2_recovery.md create mode 100644 _includes/manuals/3.12/5.5_backup_and_recovery.md create mode 100644 _includes/manuals/3.12/5.6_rails_console.md create mode 100644 _includes/manuals/3.12/5.7.1_quick_configuration.md create mode 100644 _includes/manuals/3.12/5.7.2_HBAC_rules.md create mode 100644 _includes/manuals/3.12/5.7.3_kerberos.md create mode 100644 _includes/manuals/3.12/5.7.4_pam_authentication.md create mode 100644 _includes/manuals/3.12/5.7.5_populate_users_attributes_groups.md create mode 100644 _includes/manuals/3.12/5.7.6_namespace_separation.md create mode 100644 _includes/manuals/3.12/5.7.7_openid_sso.md create mode 100644 _includes/manuals/3.12/5.7_external_authentication.md create mode 100644 _includes/manuals/3.12/5.8.1_database.md create mode 100644 _includes/manuals/3.12/5.8.2_encryption_rb.md create mode 100644 _includes/manuals/3.12/5.8.3_secret_token.md create mode 100644 _includes/manuals/3.12/5.8.4_other_considerations.md create mode 100644 _includes/manuals/3.12/5.8_multiple_foremen.md create mode 100644 _includes/manuals/3.12/5.9_http_proxy.md create mode 100644 _includes/manuals/3.12/6_plugins.md create mode 100644 _includes/manuals/3.12/7.1_novnc.md create mode 100644 _includes/manuals/3.12/7.2_debugging.md create mode 100644 _includes/manuals/3.12/7.3_getting_help.md create mode 100644 _includes/manuals/3.12/missing.html create mode 100644 manuals/3.12/index.md create mode 100644 manuals/3.12/quickstart_guide.md diff --git a/_config.yml b/_config.yml index fd910b4be7..f704f70549 100644 --- a/_config.yml +++ b/_config.yml @@ -87,6 +87,7 @@ plugins: foreman_versions: - nightly + - "3.12" - "3.11" - "3.10" - "3.9" diff --git a/_includes/manuals/3.12/1.1_architecture.md b/_includes/manuals/3.12/1.1_architecture.md new file mode 100644 index 0000000000..8185cd1b61 --- /dev/null +++ b/_includes/manuals/3.12/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) diff --git a/_includes/manuals/3.12/1.2_release_notes.md b/_includes/manuals/3.12/1.2_release_notes.md new file mode 100644 index 0000000000..c042901c21 --- /dev/null +++ b/_includes/manuals/3.12/1.2_release_notes.md @@ -0,0 +1,19 @@ +## Release notes for {{page.version}} + +This section will be updated prior to the next release. + +### Headline features + +### Upgrade warnings + +### Deprecations + +### Release Notes + +### Contributors + +We'd like to thank the following people who contributed to the Foreman {{page.version}} release: + + + +As well as all users who helped test releases, report bugs and provide feedback on the project. diff --git a/_includes/manuals/3.12/2.1_quickstart_installation.md b/_includes/manuals/3.12/2.1_quickstart_installation.md new file mode 100644 index 0000000000..ac7e91178e --- /dev/null +++ b/_includes/manuals/3.12/2.1_quickstart_installation.md @@ -0,0 +1,193 @@ +[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. + +
+ +If you want to manage content (for example, RPMs, Kickstart trees, ISO and KVM images, OSTree content, and more) with Foreman please follow the Katello installation instructions. If you are a new user, ensure that you familiarize yourself with Katello 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. + +
+ + +#### Select operating system + + + +To provide specific installation instructions, please select your operating system: + + +#### Repositories + +
+ No operating system selected. +
+ +
+

+ Enable Puppet's 7.x repository: +

+ +{% highlight bash %} +sudo dnf -y install https://yum.puppet.com/puppet7-release-el-8.noarch.rpm +{% endhighlight %} +
+ +
+

+ Enable Puppet's 7.x repository: +

+ +{% highlight bash %} +sudo dnf -y install https://yum.puppet.com/puppet7-release-el-9.noarch.rpm +{% endhighlight %} +
+ +
+

Enable the Foreman repositories:

+ +{% highlight bash %} +sudo dnf -y install https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm +{% endhighlight %} +
+ +
+

Enable the Foreman repositories:

+ +{% highlight bash %} +sudo dnf -y install https://yum.theforeman.org/releases/{{page.version}}/el9/x86_64/foreman-release.rpm +{% endhighlight %} +
+ +
+

Enable the Foreman module:

+ +{% highlight bash %} +sudo dnf -y module enable foreman:el8 +{% endhighlight %} +
+ +
+

+ Enable Puppet's 7.x repository: +

+ +{% 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 %} + +

Enable the Foreman repositories:

+ +{% 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 %} +
+ +
+

+ Enable Puppet's 7.x repository: +

+ +{% 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 %} + +

Enable the Foreman repositories:

+ +{% 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 %} +
+ +
+

+ Enable Puppet's 7.x repository: +

+ +{% highlight bash %} +sudo apt-get -y install ca-certificates +cd /tmp && wget https://apt.puppet.com/puppet7-release-jammy.deb +sudo apt-get install /tmp/puppet7-release-jammy.deb +{% endhighlight %} + +

Enable the Foreman repositories:

+ +{% highlight bash %} +sudo wget https://deb.theforeman.org/foreman.asc -O /etc/apt/trusted.gpg.d/foreman.asc +echo "deb http://deb.theforeman.org/ jammy {{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 %} +
+ +#### Downloading the installer + +
+ No operating system selected. +
+ +
+{% highlight bash %} +sudo dnf -y install foreman-installer +{% endhighlight %} +
+ +
+{% highlight bash %} +sudo apt-get update && sudo apt-get -y install foreman-installer +{% endhighlight %} +
+ +#### Running the installer + +
+ Ensure that ping $(hostname -f) shows the real IP address, not 127.0.1.1. Change or remove this entry from /etc/hosts if present. +
+ +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: + +
+{% highlight bash %} +sudo foreman-installer +{% endhighlight %} +
+ +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) diff --git a/_includes/manuals/3.12/2.2_quickstart_puppet.md b/_includes/manuals/3.12/2.2_quickstart_puppet.md new file mode 100644 index 0000000000..6475b12616 --- /dev/null +++ b/_includes/manuals/3.12/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 %} + +
Puppet will show a warning the first time that the node can't be found, this can be ignored.
+ +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. + +
Managed parameters can be overridden when editing an individual host from its Parameters tab.
+ +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. diff --git a/_includes/manuals/3.12/2_quickstart_guide.md b/_includes/manuals/3.12/2_quickstart_guide.md new file mode 100644 index 0000000000..877cf3ed12 --- /dev/null +++ b/_includes/manuals/3.12/2_quickstart_guide.md @@ -0,0 +1,18 @@ + +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 +* Enterprise Linux 9, x86_64 +* Debian 11 (Bullseye), amd64 +* Ubuntu 20.04 (Focal), amd64 +* Ubuntu 22.04 (Jammy), amd64 + +#### Enterprise Linux + +The Foreman packages and installer are tested on AlmaLinux 8, AlmaLinux 9, CentOS Stream 8 and CentOS Stream 9, 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) diff --git a/_includes/manuals/3.12/3.1.1_supported_platforms.md b/_includes/manuals/3.12/3.1.1_supported_platforms.md new file mode 100644 index 0000000000..9ca318b53a --- /dev/null +++ b/_includes/manuals/3.12/3.1.1_supported_platforms.md @@ -0,0 +1,41 @@ +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. +* Red Hat Enterprise Linux 9 + * Architectures: x86_64 only + * Apply all SELinux-related errata. +* CentOS Stream 9 + * Architectures: x86_64 only + * **Note:** + - The RPM packages are built on Red Hat Enterprise Linux 9, but tested to work also on CentOS Stream 9 + - EPEL 9 is incompatible, enabling will cause package dependency issue. +* Ubuntu 20.04 (Focal) + * Architectures: amd64 +* Ubuntu 22.04 (Jammy) + * 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 diff --git a/_includes/manuals/3.12/3.1.2_hardware_requirements.md b/_includes/manuals/3.12/3.1.2_hardware_requirements.md new file mode 100644 index 0000000000..5253e6d1a1 --- /dev/null +++ b/_includes/manuals/3.12/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. diff --git a/_includes/manuals/3.12/3.1.3_puppet_versions.md b/_includes/manuals/3.12/3.1.3_puppet_versions.md new file mode 100644 index 0000000000..2e82ad6231 --- /dev/null +++ b/_includes/manuals/3.12/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. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Puppet versionForeman installer (AIO)Foreman installer (non-AIO)Smart Proxy
0.x-5.xNot supportedNot supportedNot supported
6.xNot supportedNot supportedDeprecated
7.xSupportedUntestedSupported
+ +#### 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). + diff --git a/_includes/manuals/3.12/3.1.4_browser_compatibility.md b/_includes/manuals/3.12/3.1.4_browser_compatibility.md new file mode 100644 index 0000000000..1aabb1436a --- /dev/null +++ b/_includes/manuals/3.12/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. diff --git a/_includes/manuals/3.12/3.1.5_firewall_configuration.md b/_includes/manuals/3.12/3.1.5_firewall_configuration.md new file mode 100644 index 0000000000..a36daa86aa --- /dev/null +++ b/_includes/manuals/3.12/3.1.5_firewall_configuration.md @@ -0,0 +1,56 @@ +Protect your Foreman environment by blocking all unnecessary and unused ports. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PortProtocolRequired For
53TCP & UDPDNS Server
67, 68UDPDHCP Server
69UDPTFTP Server
80, 443TCP* HTTP & HTTPS access to Foreman web UI / provisioning templates - using Apache
3000TCPHTTP access to Foreman web UI / provisioning templates - using standalone WEBrick service
5910 - 5930TCPServer VNC Consoles
5432TCPSeparate PostgreSQL database
8140TCP* Puppet server
8443TCPSmart Proxy, open only to Foreman
+ +Ports indicated with * are running by default on a Foreman all-in-one installation and should be open. diff --git a/_includes/manuals/3.12/3.1_system_requirements.md b/_includes/manuals/3.12/3.1_system_requirements.md new file mode 100644 index 0000000000..52686819f8 --- /dev/null +++ b/_includes/manuals/3.12/3.1_system_requirements.md @@ -0,0 +1 @@ +This sections outlines the system requirements for an installation of Foreman. This will cover the hardware requirements, OS requirements and firewall requirements. This includes variations for all supported database types. diff --git a/_includes/manuals/3.12/3.2.1_installation.md b/_includes/manuals/3.12/3.2.1_installation.md new file mode 100644 index 0000000000..4e65c36f88 --- /dev/null +++ b/_includes/manuals/3.12/3.2.1_installation.md @@ -0,0 +1,21 @@ + +#### Downloading the installer + +Follow the instructions in section [2.1 Quickstart installation](/manuals/{{page.version}}/index.html#2.1Installation) + +#### Running the installer + +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, while `--noop` will run without making any changes. To run the installer, execute: + +{% highlight bash %} +foreman-installer +{% endhighlight %} + +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 %} diff --git a/_includes/manuals/3.12/3.2.2_installer_options.md b/_includes/manuals/3.12/3.2.2_installer_options.md new file mode 100644 index 0000000000..8bb453e296 --- /dev/null +++ b/_includes/manuals/3.12/3.2.2_installer_options.md @@ -0,0 +1,2547 @@ + +The installer is a collection of Puppet modules, which have a large number of parameters available to customize the configuration. Parameters can be set by running `foreman-installer` with arguments, e.g. `--foreman-initial-admin-password`, changing settings in interactive mode or by setting up an answers file. + +The precedence for settings is for those set by arguments to foreman-installer or interactive mode, then the answers file, then the Puppet manifest defaults. + +#### foreman-installer arguments + +Every parameter available in the installer can be set using command line arguments to `foreman-installer`. Run `foreman-installer --help` for most options, or `foreman-installer --full-help` for a list of every available option. + +When running the installer, all arguments passed on the command line will be persisted by default to `/etc/foreman-installer/scenarios.d/foreman-answers.yaml` and used automatically on subsequent runs, without needing to specify those arguments again. This persistence can be disabled with the `-b` option. + +#### Interactive mode + +The installer also provides a text driven interface to customize configuration parameters, and can be run by executing: + +{% highlight bash %} +foreman-installer -i +{% endhighlight %} + +#### Plugins and compute resources + +The installer contains a number of high level modules (e.g. "foreman", "puppet") and additionally a number of smaller modules for additional functionality, such as plugins and compute resource support. These can be added with the "--enable" switches, or the default options can be disabled with "--no-enable" switches. + +More information about compute resources can be found in the [Compute Resources section](/manuals/{{page.version}}/index.html#5.2ComputeResources) and plugins in the [Plugins section](/manuals/{{page.version}}/index.html#6.Plugins). + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
--[no-]enable-apache-mod-statusEnable 'apache_mod_status' puppet module
--[no-]enable-foremanEnable 'foreman' puppet module
--[no-]enable-foreman-cliEnable 'foreman_cli' puppet module
--[no-]enable-foreman-cli-ansibleEnable 'foreman_cli_ansible' puppet module
--[no-]enable-foreman-cli-azureEnable 'foreman_cli_azure' puppet module
--[no-]enable-foreman-cli-discoveryEnable 'foreman_cli_discovery' puppet module
--[no-]enable-foreman-cli-googleEnable 'foreman_cli_google' puppet module
--[no-]enable-foreman-cli-kubevirtEnable 'foreman_cli_kubevirt' puppet module
--[no-]enable-foreman-cli-openscapEnable 'foreman_cli_openscap' puppet module
--[no-]enable-foreman-cli-puppetEnable 'foreman_cli_puppet' puppet module
--[no-]enable-foreman-cli-remote-executionEnable 'foreman_cli_remote_execution' puppet module
--[no-]enable-foreman-cli-sshEnable 'foreman_cli_ssh' puppet module
--[no-]enable-foreman-cli-tasksEnable 'foreman_cli_tasks' puppet module
--[no-]enable-foreman-cli-templatesEnable 'foreman_cli_templates' puppet module
--[no-]enable-foreman-cli-webhooksEnable 'foreman_cli_webhooks' puppet module
--[no-]enable-foreman-proxyEnable 'foreman_proxy' puppet module
--[no-]enable-puppetEnable 'puppet' puppet module
--[no-]enable-foreman-plugin-acdEnable 'foreman_plugin_acd' puppet module (foreman_acd)
--[no-]enable-foreman-plugin-ansibleEnable 'foreman_plugin_ansible' puppet module (foreman_ansible)
--[no-]enable-foreman-plugin-azureEnable 'foreman_plugin_azure' puppet module (foreman_azure)
--[no-]enable-foreman-plugin-bootdiskEnable 'foreman_plugin_bootdisk' puppet module (foreman_bootdisk)
--[no-]enable-foreman-plugin-default-hostgroupEnable 'foreman_plugin_default_hostgroup' puppet module (foreman_default_hostgroup)
--[no-]enable-foreman-plugin-dhcp-browserEnable 'foreman_plugin_dhcp_browser' puppet module (foreman_dhcp_browser)
--[no-]enable-foreman-plugin-discoveryEnable 'foreman_plugin_discovery' puppet module (foreman_discovery)
--[no-]enable-foreman-plugin-dlmEnable 'foreman_plugin_dlm' puppet module (foreman_dlm)
--[no-]enable-foreman-plugin-expire-hostsEnable 'foreman_plugin_expire_hosts' puppet module (foreman_expire_hosts)
--[no-]enable-foreman-plugin-git-templatesEnable 'foreman_plugin_git_templates' puppet module (foreman_git_templates)
--[no-]enable-foreman-plugin-googleEnable 'foreman_plugin_google' puppet module (foreman_google)
--[no-]enable-foreman-plugin-host-extra-validatorEnable 'foreman_plugin_host_extra_validator' puppet module (foreman_host_extra_validator)
--[no-]enable-foreman-plugin-kubevirtEnable 'foreman_plugin_kubevirt' puppet module (foreman_kubevirt)
--[no-]enable-foreman-plugin-leappEnable 'foreman_plugin_leapp' puppet module (foreman_leapp)
--[no-]enable-foreman-plugin-monitoringEnable 'foreman_plugin_monitoring' puppet module (foreman_monitoring)
--[no-]enable-foreman-plugin-netboxEnable 'foreman_plugin_netbox' puppet module (foreman_netbox)
--[no-]enable-foreman-plugin-omahaEnable 'foreman_plugin_omaha' puppet module (foreman_omaha)
--[no-]enable-foreman-plugin-openscapEnable 'foreman_plugin_openscap' puppet module (foreman_openscap)
--[no-]enable-foreman-plugin-ovirt-provisionEnable 'foreman_plugin_ovirt_provision' puppet module (ovirt_provision_plugin)
--[no-]enable-foreman-plugin-proxmoxEnable 'foreman_plugin_proxmox' puppet module (foreman_proxmox)
--[no-]enable-foreman-plugin-puppetEnable 'foreman_plugin_puppet' puppet module (foreman_puppet)
--[no-]enable-foreman-plugin-puppetdbEnable 'foreman_plugin_puppetdb' puppet module (puppetdb_foreman)
--[no-]enable-foreman-plugin-remote-executionEnable 'foreman_plugin_remote_execution' puppet module (foreman_remote_execution)
--[no-]enable-foreman-plugin-remote-execution-cockpitEnable 'foreman_plugin_remote_execution_cockpit' puppet module (foreman_remote_execution_cockpit)
--[no-]enable-foreman-plugin-rescueEnable 'foreman_plugin_rescue' puppet module (foreman_rescue)
--[no-]enable-foreman-plugin-saltEnable 'foreman_plugin_salt' puppet module (foreman_salt)
--[no-]enable-foreman-plugin-snapshot-managementEnable 'foreman_plugin_snapshot_management' puppet module (foreman_snapshot_management)
--[no-]enable-foreman-plugin-statisticsEnable 'foreman_plugin_statistics' puppet module (foreman_statistics)
--[no-]enable-foreman-plugin-tasksEnable 'foreman_plugin_tasks' puppet module (foreman_tasks)
--[no-]enable-foreman-plugin-templatesEnable 'foreman_plugin_templates' puppet module (foreman_templates)
--[no-]enable-foreman-plugin-vaultEnable 'foreman_plugin_vault' puppet module (foreman_vault)
--[no-]enable-foreman-plugin-webhooksEnable 'foreman_plugin_webhooks' puppet module (foreman_webhooks)
--[no-]enable-foreman-plugin-wreckingballEnable 'foreman_plugin_wreckingball' puppet module (foreman_wreckingball)
--[no-]enable-foreman-compute-ec2Enable 'foreman_compute_ec2' puppet module
--[no-]enable-foreman-compute-libvirtEnable 'foreman_compute_libvirt' puppet module
--[no-]enable-foreman-compute-openstackEnable 'foreman_compute_openstack' puppet module
--[no-]enable-foreman-compute-ovirtEnable 'foreman_compute_ovirt' puppet module
--[no-]enable-foreman-compute-vmwareEnable 'foreman_compute_vmware' puppet module
--[no-]enable-foreman-proxy-plugin-acdEnable 'foreman_proxy_plugin_acd' puppet module (smart_proxy_acd)
--[no-]enable-foreman-proxy-plugin-ansibleEnable 'foreman_proxy_plugin_ansible' puppet module (smart_proxy_ansible)
--[no-]enable-foreman-proxy-plugin-dhcp-infobloxEnable 'foreman_proxy_plugin_dhcp_infoblox' puppet module (smart_proxy_dhcp_infoblox)
--[no-]enable-foreman-proxy-plugin-dhcp-remote-iscEnable 'foreman_proxy_plugin_dhcp_remote_isc' puppet module (smart_proxy_dhcp_remote_isc)
--[no-]enable-foreman-proxy-plugin-discoveryEnable 'foreman_proxy_plugin_discovery' puppet module (smart_proxy_discovery)
--[no-]enable-foreman-proxy-plugin-dns-infobloxEnable 'foreman_proxy_plugin_dns_infoblox' puppet module (smart_proxy_dns_infoblox)
--[no-]enable-foreman-proxy-plugin-dns-powerdnsEnable 'foreman_proxy_plugin_dns_powerdns' puppet module (smart_proxy_dns_powerdns)
--[no-]enable-foreman-proxy-plugin-dns-route53Enable 'foreman_proxy_plugin_dns_route53' puppet module (smart_proxy_dns_route53)
--[no-]enable-foreman-proxy-plugin-dynflowEnable 'foreman_proxy_plugin_dynflow' puppet module (smart_proxy_dynflow)
--[no-]enable-foreman-proxy-plugin-monitoringEnable 'foreman_proxy_plugin_monitoring' puppet module (smart_proxy_monitoring)
--[no-]enable-foreman-proxy-plugin-omahaEnable 'foreman_proxy_plugin_omaha' puppet module (smart_proxy_omaha)
--[no-]enable-foreman-proxy-plugin-openscapEnable 'foreman_proxy_plugin_openscap' puppet module (smart_proxy_openscap)
--[no-]enable-foreman-proxy-plugin-remote-execution-scriptEnable 'foreman_proxy_plugin_remote_execution_script' puppet module (smart_proxy_remote_execution_script)
--[no-]enable-foreman-proxy-plugin-saltEnable 'foreman_proxy_plugin_salt' puppet module (smart_proxy_salt)
--[no-]enable-foreman-proxy-plugin-shellhooksEnable 'foreman_proxy_plugin_shellhooks' puppet module (smart_proxy_shellhooks)
+
+ +#### Available options + +**Note:** When you can specify a hash, you need to specify each option individually to `foreman-installer`. + +For example the hash `{show_diff => true, stringify_facts => false}` for `--puppet-server-additional-settings` becomes `--puppet-server-additional-settings=show_diff:true --puppet-server-additional-settings=stringify_facts:false`. + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
--apache-mod-status-extended-statusDetermines whether to track extended status information for each request, via the ExtendedStatus directive.
--apache-mod-status-requiresA Variant type that can be: - String with: - '' or 'unmanaged' - Host auth control done elsewhere - 'ip <List of IPs>>' - Allowed IPs/ranges - 'host <List of names>' - Allowed names/domains - 'all [granted|denied]' - Array of strings with ip or host as above - Hash with following keys: - 'requires' - Value => Array as above - 'enforce' - Value => String 'Any', 'All' or 'None' This encloses "Require" directives in "" block Optional - If unspecified, "Require" directives follow current flow
--apache-mod-status-status-pathPath assigned to the Location directive which defines the URL to access the server status.
--foreman-apacheConfigure Apache as a reverse proxy for the Foreman server
--foreman-client-ssl-caDefines the SSL CA used to communicate with Foreman Proxies
--foreman-client-ssl-certDefines the SSL certificate used to communicate with Foreman Proxies
--foreman-client-ssl-keyDefines the SSL private key used to communicate with Foreman Proxies
--foreman-cors-domainsList of domains that show be allowed for Cross-Origin Resource Sharing
--foreman-db-databaseDatabase 'production' database (e.g. foreman)
--foreman-db-hostDatabase 'production' host
--foreman-db-manageIf enabled, will install and configure the database server on this host
--foreman-db-manage-rakeif enabled, will run rake jobs, which depend on the database
--foreman-db-passwordDatabase 'production' password, default is randomly generated
--foreman-db-poolDatabase 'production' size of connection pool. If the value is not set, it will be set by default to the amount of puma threads + 4 (for internal system threads)
--foreman-db-portDatabase 'production' port
--foreman-db-root-certRoot cert used to verify SSL connection to postgres
--foreman-db-sslmodeDatabase 'production' ssl mode
--foreman-db-usernameDatabase 'production' user (e.g. foreman)
--foreman-dynflow-manage-servicesWhether to manage the dynflow services
--foreman-dynflow-orchestrator-ensureThe state of the dynflow orchestrator instance
--foreman-dynflow-redis-urlIf set, the redis server is not managed and we use the defined url to connect
--foreman-dynflow-worker-concurrencyHow many concurrent jobs to handle per worker instance
--foreman-dynflow-worker-instancesThe number of worker instances that should be running
--foreman-email-delivery-methodEmail delivery method
--foreman-email-reply-addressEmail reply address for emails that Foreman is sending
--foreman-email-sendmail-argumentsThe arguments to pass to the sendmail binary. Unused when SMTP delivery is used.
--foreman-email-sendmail-locationThe location of the binary to call when sendmail is the delivery method. Unused when SMTP delivery is used.
--foreman-email-smtp-addressSMTP server hostname, when delivery method is SMTP
--foreman-email-smtp-authenticationSMTP authentication method
--foreman-email-smtp-domainSMTP HELO domain
--foreman-email-smtp-passwordPassword for SMTP server auth, if authentication is enabled
--foreman-email-smtp-portSMTP port
--foreman-email-smtp-user-nameUsername for SMTP server auth, if authentication is enabled
--foreman-email-subject-prefixPrefix to add to all outgoing email
--foreman-foreman-service-puma-threads-maxMaximum number of threads for every Puma worker
--foreman-foreman-service-puma-threads-minMinimum number of threads for every Puma worker. If no value is specified, this defaults to setting min threads to maximum threads. Setting min threads equal to max threads has been shown to alleviate memory leaks and in some cases produce better performance.
--foreman-foreman-service-puma-workersNumber of workers for Puma. If not set, the value is dynamically calculated based on available number of CPUs and memory.
--foreman-foreman-urlURL on which foreman is going to run
--foreman-gssapi-local-nameWhether to enable GssapiLocalName when using mod_auth_gssapi
--foreman-hsts-enabledShould HSTS enforcement in https requests be enabled
--foreman-http-keytabPath to keytab to be used for Kerberos authentication on the WebUI. If left empty, it will be automatically determined.
--foreman-initial-admin-emailInitial E-mail address of the admin user
--foreman-initial-admin-first-nameInitial first name of the admin user
--foreman-initial-admin-last-nameInitial last name of the admin user
--foreman-initial-admin-localeInitial locale (= language) of the admin user
--foreman-initial-admin-passwordInitial password of the admin user, default is randomly generated
--foreman-initial-admin-timezoneInitial timezone of the admin user
--foreman-initial-admin-usernameInitial username for the admin user account, default is admin
--foreman-initial-locationName of an initial location
--foreman-initial-organizationName of an initial organization
--foreman-ipa-authenticationEnable configuration for external authentication via IPA
--foreman-ipa-authentication-apiEnable configuration for external authentication via IPA for API
--foreman-ipa-manage-sssdIf ipa_authentication is true, should the installer manage SSSD? You can disable it if you use another module for SSSD configuration
--foreman-ipa-sssd-default-realmIf ipa_manage_sssd is true, set default_domain_suffix option in sssd configuration to this value to allow logging in without having to provide the domain name.
--foreman-keycloakEnable Keycloak support. Note this is limited to configuring Apache and still relies on manually running keycloak-httpd-client-install
--foreman-keycloak-app-nameThe app name as passed to keycloak-httpd-client-install
--foreman-keycloak-realmThe realm as passed to keycloak-httpd-client-install
--foreman-loggersEnable or disable specific loggers, e.g. {"sql" => true}
--foreman-logging-layoutLogging layout of the Foreman application
--foreman-logging-levelLogging level of the Foreman application
--foreman-logging-typeLogging type of the Foreman application
--foreman-oauth-activeEnable OAuth authentication for REST API
--foreman-oauth-consumer-keyOAuth consumer key
--foreman-oauth-consumer-secretOAuth consumer secret
--foreman-oauth-effective-userUser to be used for REST interaction
--foreman-oauth-map-usersShould Foreman use the foreman_user header to identify API user?
--foreman-pam-servicePAM service used for host-based access control in IPA
--foreman-plugin-versionForeman plugins package version, it's passed to ensure parameter of package resource can be set to 'installed', 'latest', 'present' only
--foreman-provisioning-ct-locationThe location of the binary to call when transpiling CoreOS templates.
--foreman-provisioning-fcct-locationThe location of the binary to call when transpiling Fedora CoreOS templates.
--foreman-rails-cache-storeSet rails cache store
--foreman-register-in-foremanRegister host in Foreman
--foreman-server-portDefines Apache port for HTTP requests
--foreman-server-ssl-caDefines Apache mod_ssl SSLCACertificateFile setting in Foreman vhost conf file.
--foreman-server-ssl-certDefines Apache mod_ssl SSLCertificateFile setting in Foreman vhost conf file.
--foreman-server-ssl-chainDefines Apache mod_ssl SSLCertificateChainFile setting in Foreman vhost conf file.
--foreman-server-ssl-crlDefines the Apache mod_ssl SSLCARevocationFile setting in Foreman vhost conf file.
--foreman-server-ssl-keyDefines Apache mod_ssl SSLCertificateKeyFile setting in Foreman vhost conf file.
--foreman-server-ssl-portDefines Apache port for HTTPS requests
--foreman-server-ssl-protocolDefines the Apache mod_ssl SSLProtocol setting in Foreman vhost conf file.
--foreman-server-ssl-verify-clientDefines the Apache mod_ssl SSLVerifyClient setting in Foreman vhost conf file.
--foreman-serveraliasesServer aliases of the VirtualHost in the webserver
--foreman-servernameServer name of the VirtualHost in the webserver
--foreman-sslEnable and set require_ssl in Foreman settings (note: requires Apache, SSL does not apply to kickstarts)
--foreman-telemetry-logger-enabledEnable telemetry logs - useful for telemetry debugging
--foreman-telemetry-logger-levelTelemetry debugging logs level
--foreman-telemetry-prefixPrefix for all metrics
--foreman-telemetry-prometheus-enabledEnable prometheus telemetry
--foreman-telemetry-statsd-enabledEnable statsd telemetry
--foreman-telemetry-statsd-hostStatsd host in format ip:port, do not use DNS
--foreman-telemetry-statsd-protocolStatsd protocol one of 'statsd', 'statsite' or 'datadog' - currently only statsd is supported
--foreman-trusted-proxiesList of trusted IPs / networks. Default: IPv4 and IPV6 localhost addresses. If overwritten, localhost addresses (127.0.0.1/8, ::1) need to be in trusted_proxies IP list again. More details: https://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html
--foreman-unattendedShould Foreman manage host provisioning as well
--foreman-unattended-urlURL hosts will retrieve templates from during build (normally http as many installers don't support https)
--foreman-versionForeman package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-websockets-encryptWhether to encrypt websocket connections
--foreman-websockets-ssl-certSSL certificate file to use when encrypting websocket connections
--foreman-websockets-ssl-keySSL key file to use when encrypting websocket connections
--foreman-cli-foreman-urlURL on which Foreman runs
--foreman-cli-manage-root-configWhether to manage /root/.hammer configuration.
--foreman-cli-passwordPassword for authentication
--foreman-cli-refresh-cacheCheck API documentation cache status on each request
--foreman-cli-request-timeoutAPI request timeout, set -1 for infinity
--foreman-cli-ssl-ca-filePath to SSL certificate authority
--foreman-cli-use-sessionsEnable using sessions
--foreman-cli-usernameUsername for authentication
--foreman-cli-versionforeman-cli package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-proxy-autosignfileHostname-Whitelisting only: Location of puppets autosign.conf
--foreman-proxy-bind-hostHost to bind ports to, e.g. *, localhost, 0.0.0.0
--foreman-proxy-bmcEnable BMC feature
--foreman-proxy-bmc-default-providerBMC default provider.
--foreman-proxy-bmc-listen-onBMC proxy to listen on https, http, or both
--foreman-proxy-bmc-redfish-verify-sslBMC Redfish verify ssl.
--foreman-proxy-bmc-ssh-keyBMC SSH key location.
--foreman-proxy-bmc-ssh-powercycleBMC SSH powercycle command.
--foreman-proxy-bmc-ssh-poweroffBMC SSH poweroff command.
--foreman-proxy-bmc-ssh-poweronBMC SSH poweron command.
--foreman-proxy-bmc-ssh-powerstatusBMC SSH powerstatus command.
--foreman-proxy-bmc-ssh-userBMC SSH user.
--foreman-proxy-dhcpEnable DHCP feature
--foreman-proxy-dhcp-additional-interfacesAdditional DHCP listen interfaces (in addition to dhcp_interface). Note: as opposed to dhcp_interface *no* subnet will be provisioned for any of the additional DHCP listen interfaces. Please configure any additional subnets using `dhcp::pool` and related resource types (provided by the theforeman/puppet-dhcp module).
--foreman-proxy-dhcp-configDHCP config file path
--foreman-proxy-dhcp-failover-addressAddress for DHCP to listen for connections from its peer
--foreman-proxy-dhcp-failover-portPort for DHCP to listen & communicate with it DHCP peer
--foreman-proxy-dhcp-gatewayDHCP pool gateway
--foreman-proxy-dhcp-interfaceDHCP listen interface
--foreman-proxy-dhcp-ipxe-bootstrapEnable or disable iPXE bootstrap(discovery) feature
--foreman-proxy-dhcp-ipxefilenameiPXE DHCP "filename" value, If not specified, it's determined dynamically. When the templates feature is enabled, the template_url is used.
--foreman-proxy-dhcp-key-nameDHCP key name
--foreman-proxy-dhcp-key-secretDHCP password
--foreman-proxy-dhcp-leasesDHCP leases file
--foreman-proxy-dhcp-listen-onDHCP proxy to listen on https, http, or both
--foreman-proxy-dhcp-load-balanceCutoff after which load balancing is disabled
--foreman-proxy-dhcp-load-splitSplit leases between Primary and Secondary. 255 means Primary is chiefly responsible. 0 means Secondary is chiefly responsible.
--foreman-proxy-dhcp-manage-aclsWhether to manage DHCP directory ACLs. This allows the Foreman Proxy user to access even if the directory mode is 0750.
--foreman-proxy-dhcp-managedThe DHCP daemon is managed by this module
--foreman-proxy-dhcp-max-response-delaySeconds after it will assume that connection has failed to DHCP peer
--foreman-proxy-dhcp-max-unacked-updatesHow many BNDUPD messages DHCP can send before it receives a BNDACK from the local system
--foreman-proxy-dhcp-mcltSeconds for which a lease may be renewed by either failover peer without contacting the other
--foreman-proxy-dhcp-nameserversDHCP nameservers, comma-separated
--foreman-proxy-dhcp-netmaskDHCP server netmask value, defaults otherwise to value based on IP of dhcp_interface
--foreman-proxy-dhcp-networkDHCP server network value, defaults otherwise to value based on IP of dhcp_interface
--foreman-proxy-dhcp-node-typeDHCP node type
--foreman-proxy-dhcp-omapi-portDHCP server OMAPI port
--foreman-proxy-dhcp-option-domainDHCP use the dhcpd config option domain-name
--foreman-proxy-dhcp-peer-addressThe other DHCP servers address
--foreman-proxy-dhcp-ping-free-ipPerform ICMP and TCP ping when searching free IPs from the pool. This makes sure that active IP address is not suggested as free, however in locked down network environments this can cause no free IPs.
--foreman-proxy-dhcp-providerDHCP provider for the DHCP module
--foreman-proxy-dhcp-pxefilenameDHCP "filename" value, defaults otherwise to pxelinux.0
--foreman-proxy-dhcp-pxeserverDHCP "next-server" value, defaults otherwise to IP of dhcp_interface
--foreman-proxy-dhcp-rangeSpace-separated DHCP pool range
--foreman-proxy-dhcp-search-domainsDHCP search domains option
--foreman-proxy-dhcp-serverAddress of DHCP server to manage
--foreman-proxy-dhcp-subnetsSubnets list to restrict DHCP management to
--foreman-proxy-dnsEnable DNS feature
--foreman-proxy-dns-forwardersDNS forwarders
--foreman-proxy-dns-interfaceDNS interface
--foreman-proxy-dns-listen-onDNS proxy to listen on https, http, or both
--foreman-proxy-dns-managedThe DNS daemon is managed by this module. Only supported for the nsupdate and nsupdate_gss DNS providers.
--foreman-proxy-dns-providerDNS provider
--foreman-proxy-dns-reverseDNS reverse zone name
--foreman-proxy-dns-serverAddress of DNS server to manage
--foreman-proxy-dns-tsig-keytabKerberos keytab for DNS updates using GSS-TSIG authentication
--foreman-proxy-dns-tsig-principalKerberos principal for DNS updates using GSS-TSIG authentication
--foreman-proxy-dns-ttlDNS default TTL override
--foreman-proxy-dns-zoneDNS zone name
--foreman-proxy-ensure-packages-versioncontrol extra packages version, it's passed to ensure parameter of package resource
--foreman-proxy-foreman-base-urlBase Foreman URL used for REST interaction
--foreman-proxy-foreman-ssl-caSSL CA used to verify connections when accessing the Foreman API. When not specified, the ssl_ca is used instead.
--foreman-proxy-foreman-ssl-certSSL client certificate used when accessing the Foreman API When not specified, the ssl_cert is used instead.
--foreman-proxy-foreman-ssl-keyCorresponding key to a foreman_ssl_cert certificate When not specified, the ssl_key is used instead.
--foreman-proxy-freeipa-configPath to FreeIPA default.conf configuration file
--foreman-proxy-freeipa-remove-dnsRemove DNS entries from FreeIPA when deleting hosts from realm
--foreman-proxy-groupsArray of additional groups for the foreman proxy user
--foreman-proxy-httpEnable HTTP
--foreman-proxy-http-portHTTP port to listen on (if http is enabled)
--foreman-proxy-httpbootEnable HTTPBoot feature. In most deployments this requires HTTP to be enabled as well.
--foreman-proxy-httpboot-listen-onHTTPBoot proxy to listen on https, http, or both
--foreman-proxy-keyfileDNS server keyfile path
--foreman-proxy-libvirt-connectionConnection string of libvirt DNS/DHCP provider (e.g. "qemu:///system")
--foreman-proxy-libvirt-networkNetwork for libvirt DNS/DHCP provider
--foreman-proxy-logForeman proxy log file, 'STDOUT', 'SYSLOG' or 'JOURNAL'
--foreman-proxy-log-bufferLog buffer size
--foreman-proxy-log-buffer-errorsAdditional log buffer size for errors
--foreman-proxy-log-levelForeman proxy log level
--foreman-proxy-logsEnable Logs (log buffer) feature
--foreman-proxy-logs-listen-onLogs proxy to listen on https, http, or both
--foreman-proxy-manage-puppet-groupWhether to ensure the $puppet_group exists. Also ensures group owner of ssl keys and certs is $puppet_group Not applicable when ssl is false.
--foreman-proxy-manage-servicecontrol the service, whether it should be started / enabled or not. useful, if the service should be managed by a cluster software e.g. corosync / pacemaker
--foreman-proxy-oauth-consumer-keyOAuth key to be used for REST interaction
--foreman-proxy-oauth-consumer-secretOAuth secret to be used for REST interaction
--foreman-proxy-oauth-effective-userUser to be used for REST interaction
--foreman-proxy-puppetEnable Puppet module for environment imports and Puppet runs
--foreman-proxy-puppet-api-timeoutTimeout in seconds when accessing Puppet environment classes API
--foreman-proxy-puppet-groupGroups of Foreman proxy user
--foreman-proxy-puppet-listen-onProtocols for the Puppet feature to listen on
--foreman-proxy-puppet-ssl-caSSL CA used to verify connections when accessing the Puppet master API
--foreman-proxy-puppet-ssl-certSSL certificate used when accessing the Puppet master API
--foreman-proxy-puppet-ssl-keySSL private key used when accessing the Puppet master API
--foreman-proxy-puppet-urlURL of the Puppet master itself for API requests
--foreman-proxy-puppetcaEnable Puppet CA feature
--foreman-proxy-puppetca-certificateToken-whitelisting only: Certificate to use when encrypting tokens (undef to use SSL certificate)
--foreman-proxy-puppetca-listen-onProtocols for the Puppet CA feature to listen on
--foreman-proxy-puppetca-providerWhether to use puppetca_hostname_whitelisting or puppetca_token_whitelisting
--foreman-proxy-puppetca-sign-allToken-whitelisting only: Whether to sign all CSRs without checking their token
--foreman-proxy-puppetca-token-ttlToken-whitelisting only: Fallback time (in minutes) after which tokens will expire
--foreman-proxy-puppetca-tokens-fileToken-Whitelisting only: Location of the tokens.yaml
--foreman-proxy-puppetdirPuppet var directory
--foreman-proxy-realmEnable realm management feature
--foreman-proxy-realm-keytabKerberos keytab path to authenticate realm updates
--foreman-proxy-realm-listen-onRealm proxy to listen on https, http, or both
--foreman-proxy-realm-principalKerberos principal for realm updates
--foreman-proxy-realm-providerRealm management provider
--foreman-proxy-register-in-foremanRegister proxy back in Foreman
--foreman-proxy-registered-nameProxy name which is registered in Foreman
--foreman-proxy-registered-proxy-urlProxy URL which is registered in Foreman
--foreman-proxy-registrationEnable Registration feature
--foreman-proxy-registration-listen-onRegistration proxy to listen on https, http, or both
--foreman-proxy-registration-urlURL that hosts will connect to when registering
--foreman-proxy-sslEnable SSL, ensure feature is added with "https://" protocol if true
--foreman-proxy-ssl-caSSL CA to validate the client certificates used to access the proxy
--foreman-proxy-ssl-certSSL certificate to be used to run the foreman proxy via https.
--foreman-proxy-ssl-disabled-ciphersList of OpenSSL cipher suite names that will be disabled from the default
--foreman-proxy-ssl-keyCorresponding key to a ssl_cert certificate
--foreman-proxy-ssl-portHTTPS port to listen on (if ssl is enabled)
--foreman-proxy-ssldirPuppet CA SSL directory
--foreman-proxy-template-urlURL a client should use for provisioning templates
--foreman-proxy-templatesEnable templates feature
--foreman-proxy-templates-listen-onTemplates proxy to listen on https, http, or both
--foreman-proxy-tftpEnable TFTP feature
--foreman-proxy-tftp-dirsDirectories to be create in $tftp_root
--foreman-proxy-tftp-listen-onTFTP proxy to listen on https, http, or both
--foreman-proxy-tftp-manage-wgetIf enabled will install the wget package
--foreman-proxy-tftp-managedThe TFTP daemon is managed by this module.
--foreman-proxy-tftp-replace-grub2-cfgDetermines if grub2.cfg will be replaced
--foreman-proxy-tftp-rootTFTP root directory
--foreman-proxy-tftp-servernameDefines the TFTP Servername to use, overrides the name in the subnet declaration
--foreman-proxy-tls-disabled-versionsList of TLS versions that will be disabled from the default
--foreman-proxy-trusted-hostsOnly hosts listed will be permitted, empty array to disable authorization
--foreman-proxy-versionforeman package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--puppet-additional-settingsA hash of additional main settings.
--puppet-agentShould a puppet agent be installed
--puppet-agent-additional-settingsA hash of additional agent settings. Example: {stringify_facts => true}
--puppet-agent-default-schedulesA boolean to enable/disable the default schedules
--puppet-agent-noopRun the agent in noop mode.
--puppet-agent-restart-commandThe command which gets excuted on puppet service restart
--puppet-agent-server-hostnameHostname of your puppetserver (server directive in puppet.conf)
--puppet-agent-server-portOverride the port of the server we connect to.
--puppet-allow-any-crl-authAllow any authentication for the CRL. This is needed on the puppet CA to accept clients from a the puppet CA proxy.
--puppet-auth-allowedAn array of authenticated nodes allowed to access all catalog and node endpoints. default to ['$1']
--puppet-autosignIf set to a boolean, autosign is enabled or disabled for all incoming requests. Otherwise this has to be set to the full file path of an autosign.conf file or an autosign script. If this is set to a script, make sure that script considers the content of autosign.conf as otherwise Foreman functionality might be broken.
--puppet-autosign-contentIf set, write the autosign file content using the value of this parameter. Cannot be used at the same time as autosign_entries For example, could be a string, or file('another_module/autosign.sh') or template('another_module/autosign.sh.erb')
--puppet-autosign-entriesA list of certnames or domain name globs whose certificate requests will automatically be signed. Defaults to an empty Array.
--puppet-autosign-modemode of the autosign file/script
--puppet-autosign-sourceIf set, use this as the source for the autosign file, instead of autosign_content.
--puppet-ca-crl-filepathPath to CA CRL file, dynamically resolves based on $::server_ca status.
--puppet-ca-portPuppet CA port
--puppet-ca-serverUse a different ca server. Should be either a string with the location of the ca_server or 'false'.
--puppet-certificate-revocationWhether certificate revocation checking should be enabled, and what level of checking should be performed
--puppet-classfileThe file in which puppet agent stores a list of the classes associated with the retrieved configuration.
--puppet-client-certnameThe node's certificate name, and the unique identifier it uses when requesting catalogs.
--puppet-client-packageInstall a custom package to provide the puppet client
--puppet-codedirOverride the puppet code directory.
--puppet-cron-cmdSpecify command to launch when runmode is set 'cron'.
--puppet-dirOverride the puppet directory.
--puppet-dir-groupGroup of the base puppet directory, used when puppet::server is false.
--puppet-dir-ownerOwner of the base puppet directory, used when puppet::server is false.
--puppet-dns-alt-namesUse additional DNS names when generating a certificate. Defaults to an empty Array.
--puppet-environmentDefault environment of the Puppet agent
--puppet-groupOverride the name of the puppet group.
--puppet-hiera-configThe hiera configuration file.
--puppet-http-connect-timeoutThe maximum amount of time an agent waits when establishing an HTTP connection.
--puppet-http-read-timeoutThe time an agent waits for one block to be read from an HTTP connection. If nothing is read after the elapsed interval then the connection will be closed.
--puppet-localconfigThe localconfig setting.
--puppet-logdirOverride the log directory.
--puppet-manage-packagesShould this module install packages or not. Can also install only server packages with value of 'server' or only agent packages with 'agent'.
--puppet-module-repositoryUse a different puppet module repository
--puppet-package-install-optionsFlags that should be passed to the package manager during installation. Defaults to undef. May be a string, an array or a hash, see Puppet Package resource documentation for the provider matching your package manager
--puppet-package-providerThe provider used to install the agent. Defaults to chocolatey on Windows Defaults to undef elsewhere
--puppet-package-sourceThe location of the file to be used by the agent's package resource. Defaults to undef. If 'windows' or 'msi' are used as the provider then this setting is required.
--puppet-pluginfactsourceURL to retrieve Puppet facts from during pluginsync
--puppet-pluginsourceURL to retrieve Puppet plugins from during pluginsync
--puppet-postrun-commandA command which gets excuted after each Puppet run
--puppet-prerun-commandA command which gets excuted before each Puppet run
--puppet-puppetconf-modeThe permissions for /etc/puppetlabs/puppet/puppet.conf default to '0644' and '0674' on windows
--puppet-reportSend reports to the Puppet Master
--puppet-run-hourThe hour at which to run the puppet agent when runmode is cron or systemd.timer.
--puppet-run-minuteThe minute at which to run the puppet agent when runmode is cron or systemd.timer.
--puppet-rundirOverride the PID directory.
--puppet-runintervalSet up the interval (in seconds) to run the puppet agent.
--puppet-runmodeSelect the mode to setup the puppet agent.
--puppet-serverShould a puppet server be installed as well as the client
--puppet-server-acceptor-threadsThis sets the number of threads that the webserver will dedicate to accepting socket connections for unencrypted HTTP traffic. If not provided, the webserver defaults to the number of virtual cores on the host divided by 8, with a minimum of 1 and maximum of 4.
--puppet-server-additional-settingsA hash of additional settings. Example: {trusted_node_data => true, ordering => 'manifest'}
--puppet-server-admin-api-allowlistThe allowlist of clients that can query the puppet-admin-api endpoint Defaults to [ '127.0.0.1', '::1', $::ipaddress ]
--puppet-server-allow-header-cert-infoEnable client authentication over HTTP Headers Defaults to false, is also activated by the $server_http setting
--puppet-server-caProvide puppet CA
--puppet-server-ca-allow-auth-extensionsAllow CA to sign certificate requests that have authorization extensions Defaults to false
--puppet-server-ca-allow-auto-renewalEnable the auto renewal for client certificates Defaults to false
--puppet-server-ca-allow-auto-renewal-cert-ttlSet the auto renewal interval for client certificates Defaults to 60d
--puppet-server-ca-allow-sansAllow CA to sign certificate requests that have Subject Alternative Names Defaults to false
--puppet-server-ca-auth-requiredWhether client certificates are needed to access the puppet-admin api Defaults to true
--puppet-server-ca-client-allowlistThe allowlist of client certificates that can query the certificate-status endpoint Defaults to [ '127.0.0.1', '::1', $::ipaddress ]
--puppet-server-ca-client-self-deleteAdds a rule to auth.conf, that allows a client to delete its own certificate Defaults to false
--puppet-server-ca-crl-syncSync puppet CA crl file to compilers, Puppet CA Must be the Puppetserver for the compilers. Defaults to false.
--puppet-server-ca-enable-infra-crlEnable the separate CRL for Puppet infrastructure nodes Defaults to false
--puppet-server-certnameThe name to use when handling certificates.
--puppet-server-check-for-updatesShould the puppetserver phone home to check for available updates? Defaults to true
--puppet-server-cipher-suitesList of SSL ciphers to use in negotiation Defaults to ['TLS_AES_128_GCM_SHA256', 'TLS_AES_256_GCM_SHA384', 'TLS_DHE_RSA_WITH_AES_128_GCM_SHA256', 'TLS_DHE_RSA_WITH_AES_256_GCM_SHA384', 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256', 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384', 'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256', 'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384']
--puppet-server-common-modules-pathCommon modules paths
--puppet-server-compile-modeUsed to control JRuby's "CompileMode", which may improve performance. Defaults to undef (off).
--puppet-server-connect-timeoutHow long the server will wait for a response to a connection attempt
--puppet-server-crl-enableTurn on crl checking. Defaults to true when server_ca is true. Otherwise Defaults to false. Note unless you are using an external CA. It is recommended to set this to true. See $server_ca_crl_sync to enable syncing from CA Puppet Master
--puppet-server-custom-trusted-oid-mappingA hash of custom trusted oid mappings. Defaults to undef Example: { 1.3.6.1.4.1.34380.1.2.1.1 => { shortname => 'myshortname' } }
--puppet-server-default-manifestToggle if default_manifest setting should be added to the [main] section
--puppet-server-default-manifest-contentA string to set the content of the default_manifest If set to '' it will not manage the file
--puppet-server-default-manifest-pathA string setting the path to the default_manifest
--puppet-server-dirPuppet configuration directory
--puppet-server-environment-class-cache-enabledEnable environment class cache in conjunction with the use of the environment_classes API. Defaults to false
--puppet-server-environment-timeoutTimeout for cached compiled catalogs (10s, 5m, ...)
--puppet-server-environment-varsA hash of environment variables and their values which the puppetserver is allowed to see. To define literal values double quotes should be used: {'MYVAR': '"MYVALUE"'}. Omitting the inner quotes might lead to unexpected results since the HOCON format does not allow characters like $, curly/square brackets or = in unquoted strings. Multi line strings are also allowed as long as they are triple quoted: {'MYVAR': "\"\"\"MY\nMULTI\nLINE\nVALUE\"\"\""} To pass an existing variable use substitutions: {'MYVAR': '${MYVAR}'}.
--puppet-server-environments-groupThe group owning the environments directory
--puppet-server-environments-modeEnvironments directory mode.
--puppet-server-environments-ownerThe owner of the environments directory
--puppet-server-environments-recurseShould the environments directory be managed recursively
--puppet-server-envs-dirList of directories which hold puppet environments
--puppet-server-envs-targetIndicates that $envs_dir should be a symbolic link to this target
--puppet-server-external-nodesExternal nodes classifier executable
--puppet-server-foremanShould foreman integration be installed
--puppet-server-foreman-factsShould foreman receive facts from puppet
--puppet-server-foreman-ssl-caSSL CA of the Foreman server
--puppet-server-foreman-ssl-certClient certificate for authenticating against Foreman server
--puppet-server-foreman-ssl-keyKey for authenticating against Foreman server
--puppet-server-foreman-urlForeman URL
--puppet-server-git-branch-mapGit branch to puppet env mapping for the default post receive hook
--puppet-server-git-repoUse git repository as a source of modules
--puppet-server-git-repo-groupGit repository group
--puppet-server-git-repo-hook-modeGit repository hook mode
--puppet-server-git-repo-pathGit repository path on disk
--puppet-server-git-repo-umaskUmask used during git operations
--puppet-server-git-repo-userGit repository user
--puppet-server-groupGroup used for the puppetserver process
--puppet-server-httpShould the puppet server listen on HTTP as well as HTTPS. Useful for load balancer or reverse proxy scenarios.
--puppet-server-http-portPuppet server HTTP port; defaults to 8139.
--puppet-server-idle-timeoutHow long the server will wait for a response on an existing connection
--puppet-server-ipBind ip address of the puppetserver
--puppet-server-jolokia-metrics-allowlistThe allowlist of clients that can query the jolokia /metrics/v2 endpoint
--puppet-server-jruby-gem-homeWhere jruby gems are located for puppetserver
--puppet-server-jvm-cli-argsJava options to use when using puppetserver subcommands (eg puppetserver gem).
--puppet-server-jvm-configSpecify the puppetserver jvm configuration file.
--puppet-server-jvm-extra-argsAdditional java options to pass through. This can be used for Java versions prior to Java 8 to specify the max perm space to use: For example: '-XX:MaxPermSize=128m'.
--puppet-server-jvm-java-binSet the default java to use. If unspecified, it will be derived from the Puppet version.
--puppet-server-jvm-max-heap-sizeSpecify the maximum jvm heap space.
--puppet-server-jvm-min-heap-sizeSpecify the minimum jvm heap space.
--puppet-server-manage-userWhether to manage the server user resource
--puppet-server-max-active-instancesMax number of active jruby instances. Defaults to processor count
--puppet-server-max-open-filesIncrease the max open files limit for Puppetserver. Defaults to undef
--puppet-server-max-queued-requestsThe maximum number of requests that may be queued waiting to borrow a JRuby from the pool. Defaults to 0 (disabled).
--puppet-server-max-requests-per-instanceMax number of requests a jruby instances will handle. Defaults to 0 (disabled)
--puppet-server-max-retry-delaySets the upper limit for the random sleep set as a Retry-After header on 503 responses returned when max-queued-requests is enabled. Defaults to 1800.
--puppet-server-max-threadsThis sets the maximum number of threads assigned to responding to HTTP and/or HTTPS requests for a single webserver, effectively changing how many concurrent requests can be made at one time. If not provided, the webserver defaults to 200.
--puppet-server-metrics-allowedSpecify metrics to allow in addition to those in the default list Defaults to undef
--puppet-server-metrics-graphite-enableEnable or disable Graphite metrics reporter. Defaults to false
--puppet-server-metrics-graphite-hostGraphite server host. Defaults to "127.0.0.1"
--puppet-server-metrics-graphite-intervalHow often to send metrics to graphite (in seconds) Defaults to 5
--puppet-server-metrics-graphite-portGraphite server port. Defaults to 2003
--puppet-server-metrics-jmx-enableEnable or disable JMX metrics reporter. Defaults to true
--puppet-server-metrics-server-idA server id that will be used as part of the namespace for metrics produced Defaults to $fqdn
--puppet-server-multithreadedUse multithreaded jruby. Defaults to false.
--puppet-server-packageCustom package name for puppet server
--puppet-server-parserSets the parser to use. Valid options are 'current' or 'future'. Defaults to 'current'.
--puppet-server-portPuppet server port
--puppet-server-post-hook-contentWhich template to use for git post hook
--puppet-server-post-hook-nameName of a git hook
--puppet-server-puppet-basedirWhere is the puppet code base located
--puppet-server-puppetserver-auth-templateTemplate for generating /etc/puppetlabs/puppetserver/conf.d/auth.conf
--puppet-server-puppetserver-dirThe path of the puppetserver config dir
--puppet-server-puppetserver-experimentalEnable the /puppet/experimental route? Defaults to true
--puppet-server-puppetserver-logdirThe path of the puppetserver log dir
--puppet-server-puppetserver-metricsEnable puppetserver http-client metrics
--puppet-server-puppetserver-profilerEnable JRuby profiling. If set to false, compiler and function metrics will not be available, (eg. when enabling graphite metrics)
--puppet-server-puppetserver-rundirThe path of the puppetserver run dir
--puppet-server-puppetserver-telemetryEnable Dropsonde telemetry. Undef means disabled while booleans are explicit opt-in or opt-out. This is different from Puppetserver's default values.
--puppet-server-puppetserver-trusted-agentsCertificate names of puppet agents that are allowed to fetch *all* catalogs Defaults to [] and all agents are only allowed to fetch their own catalogs.
--puppet-server-puppetserver-trusted-certificate-extensionsAn array of hashes of certificate extensions and values to be used in auth.conf
--puppet-server-puppetserver-vardirThe path of the puppetserver var dir
--puppet-server-puppetserver-versionThe version of puppetserver installed (or being installed) Unfortunately, different versions of puppetserver need configuring differently. The default is derived from the installed puppet version. Generally it's not needed to override this but when upgrading it might be.
--puppet-server-reportsList of report types to include on the puppetserver
--puppet-server-request-timeoutTimeout in node.rb script for fetching catalog from Foreman (in seconds).
--puppet-server-ruby-load-pathsList of ruby paths
--puppet-server-selector-threadsThis sets the number of selectors that the webserver will dedicate to processing events on connected sockets for unencrypted HTTPS traffic. If not provided, the webserver defaults to the minimum of: virtual cores on the host divided by 2 or max-threads divided by 16, with a minimum of 1.
--puppet-server-ssl-acceptor-threadsThis sets the number of threads that the webserver will dedicate to accepting socket connections for encrypted HTTPS traffic. If not provided, defaults to the number of virtual cores on the host divided by 8, with a minimum of 1 and maximum of 4.
--puppet-server-ssl-chain-filepathPath to certificate chain for puppetserver Only used when $ca is true Defaults to "${ssl_dir}/ca/ca_crt.pem"
--puppet-server-ssl-dirSSL directory
--puppet-server-ssl-dir-manageToggle if ssl_dir should be added to the [server] configuration section. This is necessary to disable in case CA is delegated to a separate instance
--puppet-server-ssl-key-manageToggle if "private_keys/${::puppet::server::certname}.pem" should be created with default user and group. This is used in the default Forman setup to reuse the key for TLS communication.
--puppet-server-ssl-protocolsArray of SSL protocols to use. Defaults to [ 'TLSv1.3', 'TLSv1.2' ]
--puppet-server-ssl-selector-threadsThis sets the number of selectors that the webserver will dedicate to processing events on connected sockets for encrypted HTTPS traffic. Defaults to the number of virtual cores on the host divided by 2, with a minimum of 1 and maximum of 4. The number of selector threads actually used by Jetty is twice the number of selectors requested. For example, if a value of 3 is specified for the ssl-selector-threads setting, Jetty will actually use 6 selector threads.
--puppet-server-storeconfigsWhether to enable storeconfigs
--puppet-server-strict-variablesif set to true, it will throw parse errors when accessing undeclared variables.
--puppet-server-trusted-external-commandThe external trusted facts script to use.
--puppet-server-userUsername used for the puppetserver process
--puppet-server-versionCustom package version for puppet server
--puppet-server-versioned-code-contentContains the path to an executable script that Puppet Server invokes when on static_file_content requests. Defaults to undef
--puppet-server-versioned-code-idThe path to an executable script that Puppet Server invokes to generate a code_id Defaults to undef
--puppet-server-web-idle-timeoutTime in ms that Jetty allows a socket to be idle, after processing has completed. Defaults to 30000, using the Jetty default of 30s
--puppet-service-nameThe name of the puppet agent service.
--puppet-sharedirOverride the system data directory.
--puppet-show-diffShow and report changed files with diff output
--puppet-splaySwitch to enable a random amount of time to sleep before each run.
--puppet-splaylimitThe maximum time to delay before runs. Defaults to being the same as the run interval. This setting can be a time interval in seconds (30 or 30s), minutes (30m), hours (6h), days (2d), or years (5y).
--puppet-srv-domainSearch domain for SRV records
--puppet-ssldirOverride where SSL certificates are kept.
--puppet-syslogfacilityFacility name to use when logging to syslog
--puppet-systemd-cmdSpecify command to launch when runmode is set 'systemd.timer'.
--puppet-systemd-randomizeddelaysecAdds a random delay between 0 and this value (in seconds) to the timer. Only relevant when runmode is 'systemd.timer'.
--puppet-systemd-unit-nameThe name of the puppet systemd units.
--puppet-unavailable-runmodesRunmodes that are not available for the current system. This module will not try to disable these modes. Default is [] on Linux, ['cron', 'systemd.timer'] on Windows and ['systemd.timer'] on other systems.
--puppet-use-srv-recordsWhether DNS SRV records will be used to resolve the Puppet server
--puppet-usecacheonfailureSwitch to enable use of cached catalog on failure of run.
--puppet-userOverride the name of the puppet user.
--puppet-vardirOverride the puppet var directory.
--puppet-versionSpecify a specific version of a package to install. The version should be the exact match for your distro. You can also use certain values like 'latest'. Note that when you specify exact versions you should also override $server_version since that defaults to $version.
--foreman-plugin-default-hostgroup-hostgroupsAn array of hashes of hostgroup names and facts to add to the configuration
--foreman-plugin-puppetdb-addressAddress of puppetdb API.
--foreman-plugin-puppetdb-api-versionPuppetDB API version.
--foreman-plugin-puppetdb-ssl-ca-fileCA certificate file which will be used to connect to the PuppetDB API.
--foreman-plugin-puppetdb-ssl-certificateCertificate file which will be used to connect to the PuppetDB API.
--foreman-plugin-puppetdb-ssl-private-keyPrivate key file which will be used to connect to the PuppetDB API.
--foreman-plugin-remote-execution-cockpit-ensureSpecify the package state, or absent to remove it
--foreman-plugin-remote-execution-cockpit-originsSpecify additional Cockpit Origins to configure cockpit.conf. The $foreman_url is included by default.
--foreman-plugin-tasks-automatic-cleanupEnable automatic task cleanup using a cron job
--foreman-plugin-tasks-backupEnable creating a backup of cleaned up tasks in CSV format when automatic_cleanup is enabled
--foreman-plugin-tasks-cron-lineCron line defining when the cleanup cron job should run
--foreman-compute-ec2-versionPackage version to install, defaults to installed
--foreman-compute-libvirt-versionPackage version to install, defaults to installed
--foreman-compute-openstack-versionPackage version to install, defaults to installed
--foreman-compute-ovirt-versionPackage version to install, defaults to installed
--foreman-compute-vmware-versionPackage version to install, defaults to installed
--foreman-proxy-plugin-acd-enabledenables/disables the acd plugin
--foreman-proxy-plugin-acd-listen-onproxy feature listens on http, https, or both
--foreman-proxy-plugin-acd-versionplugin package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-proxy-plugin-ansible-ansible-dirAnsible directory to search for available roles
--foreman-proxy-plugin-ansible-callbackThe callback plugin to configure in ansible.cfg
--foreman-proxy-plugin-ansible-collections-pathsPaths where to look for ansible collections
--foreman-proxy-plugin-ansible-enabledEnables/disables the ansible plugin
--foreman-proxy-plugin-ansible-host-key-checkingWhether to ignore errors when a host is reinstalled so it has a different key in ~/.ssh/known_hosts If a host is not initially in 'known_hosts' setting this to True will result in prompting for confirmation of the key, which is not possible from non-interactive environments like Foreman Remote Execution or cron
--foreman-proxy-plugin-ansible-install-runnerIf true, installs ansible-runner package to support running ansible by ansible-runner
--foreman-proxy-plugin-ansible-listen-onProxy feature listens on https, http, or both
--foreman-proxy-plugin-ansible-roles-pathPaths where we look for ansible roles.
--foreman-proxy-plugin-ansible-runner-package-nameThe name of the ansible-runner package to install
--foreman-proxy-plugin-ansible-ssh-argsThe ssh_args parameter in ansible.cfg under [ssh_connection]
--foreman-proxy-plugin-ansible-working-dirA directory where the playbooks will be generated. A tmp directory will be created when left blank
--foreman-proxy-plugin-dhcp-infoblox-dns-viewThe DNS view to use
--foreman-proxy-plugin-dhcp-infoblox-network-viewThe network view to use
--foreman-proxy-plugin-dhcp-infoblox-passwordThe password of the Infoblox user
--foreman-proxy-plugin-dhcp-infoblox-record-typeRecord type to manage
--foreman-proxy-plugin-dhcp-infoblox-used-ips-search-typeThe search type for used ips
--foreman-proxy-plugin-dhcp-infoblox-usernameThe username of the Infoblox user
--foreman-proxy-plugin-dhcp-remote-isc-dhcp-configDHCP config file path
--foreman-proxy-plugin-dhcp-remote-isc-dhcp-leasesDHCP leases file
--foreman-proxy-plugin-dhcp-remote-isc-key-nameDHCP key name
--foreman-proxy-plugin-dhcp-remote-isc-key-secretDHCP password
--foreman-proxy-plugin-dhcp-remote-isc-omapi-portDHCP server OMAPI port
--foreman-proxy-plugin-discovery-enabledWhether the module is enabled or disabled.
--foreman-proxy-plugin-discovery-image-nametarball with images
--foreman-proxy-plugin-discovery-install-imagesDownload and extract the discovery image
--foreman-proxy-plugin-discovery-listen-onWhen enabled, it's configured to listen on HTTPS (default), HTTP or both.
--foreman-proxy-plugin-discovery-source-urlsource URL to download from
--foreman-proxy-plugin-discovery-tftp-rootTFTP root directory where extracted discovery image will be installed
--foreman-proxy-plugin-discovery-versionThe version to ensure
--foreman-proxy-plugin-dns-infoblox-dns-serverThe address of the Infoblox server
--foreman-proxy-plugin-dns-infoblox-dns-viewThe Infoblox DNS View
--foreman-proxy-plugin-dns-infoblox-passwordThe password of the Infoblox user
--foreman-proxy-plugin-dns-infoblox-usernameThe username of the Infoblox user
--foreman-proxy-plugin-dns-powerdns-rest-api-keyThe REST API key
--foreman-proxy-plugin-dns-powerdns-rest-urlThe REST API URL
--foreman-proxy-plugin-dns-route53-aws-access-keyThe Access Key ID of the IAM account
--foreman-proxy-plugin-dns-route53-aws-secret-keyThe Secret Access Key of the IAM account
--foreman-proxy-plugin-dynflow-console-authWhether to enable trusted hosts and ssl for the dynflow console
--foreman-proxy-plugin-dynflow-database-pathPath to the SQLite database file, set empty for in-memory sqlite
--foreman-proxy-plugin-dynflow-enabledEnables/disables the dynflow plugin
--foreman-proxy-plugin-dynflow-listen-onProxy feature listens on https, http, or both
--foreman-proxy-plugin-dynflow-open-file-limitLimit number of open files - Only Red Hat Operating Systems with Software Collections.
--foreman-proxy-plugin-dynflow-ssl-disabled-ciphersDisable SSL ciphers. For example: ['NULL-MD5', 'NULL-SHA']
--foreman-proxy-plugin-dynflow-tls-disabled-versionsDisable TLS versions. Version 1.0 is always disabled. For example: ['1.1']
--foreman-proxy-plugin-monitoring-collect-statuscollect monitoring status from monitoring solution
--foreman-proxy-plugin-monitoring-enabledenables/disables the monitoring plugin
--foreman-proxy-plugin-monitoring-listen-onproxy feature listens on http, https, or both
--foreman-proxy-plugin-monitoring-providersmonitoring providers
--foreman-proxy-plugin-monitoring-versionplugin package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-proxy-plugin-omaha-contentpathPath where omaha content is stored
--foreman-proxy-plugin-omaha-distributiondistribution type, it's passed to specify the distribution type. can be set to one of 'coreos' (default), 'flatcar'
--foreman-proxy-plugin-omaha-enabledenables/disables the omaha plugin
--foreman-proxy-plugin-omaha-http-proxyURL to a proxy server that should be used to retrieve omaha content, e.g. 'http://proxy.example.com:3128/'
--foreman-proxy-plugin-omaha-listen-onproxy feature listens on http, https, or both
--foreman-proxy-plugin-omaha-sync-releasesHow many of the latest releases should be synced
--foreman-proxy-plugin-omaha-versionplugin package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-proxy-plugin-openscap-ansible-moduleEnsure the Ansible module
--foreman-proxy-plugin-openscap-ansible-module-ensureThe state of the Ansible module to ensure
--foreman-proxy-plugin-openscap-contentdirDirectory where OpenSCAP content XML are stored So we will not request the XML from Foreman each time
--foreman-proxy-plugin-openscap-corrupted-dirDirectory where corrupted OpenSCAP report XML are stored
--foreman-proxy-plugin-openscap-enabledenables/disables the openscap plugin
--foreman-proxy-plugin-openscap-failed-dirDirectory where OpenSCAP report XML are stored In case sending to Foreman succeeded, yet failed to save to reportsdir
--foreman-proxy-plugin-openscap-listen-onProxy feature listens on http, https, or both
--foreman-proxy-plugin-openscap-openscap-send-log-fileLog file for the forwarding script
--foreman-proxy-plugin-openscap-proxy-nameProxy name to send to Foreman with parsed report Foreman matches it against names of registered proxies to find the report source
--foreman-proxy-plugin-openscap-puppet-moduleEnsure the Puppet module. This only makes sense if Puppetserver runs on the same machine.
--foreman-proxy-plugin-openscap-puppet-module-ensureThe state of the Puppet module to ensure
--foreman-proxy-plugin-openscap-reportsdirDirectory where OpenSCAP report XML are stored So Foreman can request arf xml reports
--foreman-proxy-plugin-openscap-spooldirDirectory where OpenSCAP audits are stored before they are forwarded to Foreman
--foreman-proxy-plugin-openscap-timeoutTimeout for sending ARF reports to foreman
--foreman-proxy-plugin-openscap-versionplugin package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
--foreman-proxy-plugin-remote-execution-script-cockpit-integrationEnables/disables Cockpit integration
--foreman-proxy-plugin-remote-execution-script-enabledEnables/disables the plugin
--foreman-proxy-plugin-remote-execution-script-generate-keysAutomatically generate SSH keys
--foreman-proxy-plugin-remote-execution-script-install-keyAutomatically install generated SSH key to root authorized keys which allows managing this host through Remote Execution
--foreman-proxy-plugin-remote-execution-script-listen-onProxy feature listens on https, http, or both
--foreman-proxy-plugin-remote-execution-script-local-working-dirLocal working directory on the smart proxy
--foreman-proxy-plugin-remote-execution-script-modeOperation Mode of the plugin.
--foreman-proxy-plugin-remote-execution-script-mqtt-rate-limitNumber of jobs that are allowed to run at the same time
--foreman-proxy-plugin-remote-execution-script-mqtt-resend-intervalTime interval in seconds at which the notification should be re-sent to the host until the job is picked up or canceleld
--foreman-proxy-plugin-remote-execution-script-mqtt-ttlTime interval in seconds given to the host to pick up the job before considering the job undelivered.
--foreman-proxy-plugin-remote-execution-script-remote-working-dirRemote working directory on clients
--foreman-proxy-plugin-remote-execution-script-ssh-identity-dirDirectory where SSH keys are stored
--foreman-proxy-plugin-remote-execution-script-ssh-identity-fileProvide an alternative name for the SSH keys
--foreman-proxy-plugin-remote-execution-script-ssh-kerberos-authEnable kerberos authentication for SSH
--foreman-proxy-plugin-remote-execution-script-ssh-keygenLocation of the ssh-keygen binary
--foreman-proxy-plugin-remote-execution-script-ssh-log-levelConfigure ssh client LogLevel
--foreman-proxy-plugin-salt-apiUse Salt API
--foreman-proxy-plugin-salt-api-authSalt API auth mechanism
--foreman-proxy-plugin-salt-api-passwordSalt API password
--foreman-proxy-plugin-salt-api-urlSalt API URL
--foreman-proxy-plugin-salt-api-usernameSalt API username
--foreman-proxy-plugin-salt-autosign-fileFile to use for salt autosign
--foreman-proxy-plugin-salt-autosign-key-fileFile to use for salt autosign via grains
--foreman-proxy-plugin-salt-enabledEnables/disables the salt plugin
--foreman-proxy-plugin-salt-groupGroup to run salt commands and access configuration files
--foreman-proxy-plugin-salt-listen-onProxy feature listens on https, http, or both
--foreman-proxy-plugin-salt-saltfilePath to Saltfile
--foreman-proxy-plugin-salt-userUser to run salt commands under
--foreman-proxy-plugin-shellhooks-directoryAbsolute path to directory with executables
--foreman-proxy-plugin-shellhooks-enabledenables/disables the shellhooks plugin
--foreman-proxy-plugin-shellhooks-listen-onproxy feature listens on http, https, or both
--foreman-proxy-plugin-shellhooks-versionplugin package version, it's passed to ensure parameter of package resource can be set to specific version number, 'latest', 'present' etc.
+
+ +#### Answers file + +The answers file describes the classes that will be applied to the host to +install Foreman, along with their parameters. The foreman-installer package stores it at `/etc/foreman-installer/scenarios.d/foreman-answers.yaml`. By default, the *all-in-one* setup will include Foreman, a puppetmaster, Puppet agent, and the Smart Proxy: + +{% highlight yaml %} +--- +foreman: true +foreman_proxy: true +puppet: + server: true +{% endhighlight %} + +Other examples are given in the next section, or `/usr/share/foreman-installer/README.md`. + +#### Advanced module configuration + +Additional configuration options can be given in `/etc/foreman-installer/custom-hiera.yaml` for some of the Puppet modules that are used internally by Foreman installer. The contents of this file will be passed to Hiera during the Foreman installer execution so can set class parameters for other modules such as `apache`, `mysql`, and `postgresql`. + +For example, the `TraceEnable` option may be controlled by disabling the `apache::trace_enable` parameter in this file: + +{% highlight yaml %} +apache::trace_enable: Off +{% endhighlight %} + +Please note that the parameters used by these modules may change between versions of Foreman, so it's important to check the versions in use and the appropriate module documentation or source code when editing this configuration file. Modifications cannot be supported or migrated by Foreman. diff --git a/_includes/manuals/3.12/3.2.3_installation_scenarios.md b/_includes/manuals/3.12/3.2.3_installation_scenarios.md new file mode 100644 index 0000000000..3c43082718 --- /dev/null +++ b/_includes/manuals/3.12/3.2.3_installation_scenarios.md @@ -0,0 +1,192 @@ + +The Foreman installer can accommodate more complex, multi-host setups when supplied with appropriate parameters. + +#### Using an external database server + +Per default foreman-installer will install a PostgreSQL database server onto the Foreman host and create its database. An external database server with an already created database can be used with the following arguments: + +{% highlight bash %} +foreman-installer \ + --foreman-db-manage=false \ + --foreman-db-host=dbserver.example.com \ + --foreman-db-database=dbname \ + --foreman-db-username=dbuser \ + --foreman-db-password=dbpassword +{% endhighlight %} + +As a post-installation step, to populate the database correctly, run: + +{% highlight bash %} +foreman-rake db:migrate +foreman-rake db:seed +foreman-rake apipie:cache:index +{% endhighlight %} + +#### Setting up Foreman with additional Smart Proxies + +Using the scenarios outlined below, a simple scale-out setup can be created as follows: + +1. 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. + +For each additional Smart Proxy: + +1. Bootstrap certificates +1. Run the standalone installation as detailed below + +**Note** This relies on the puppet ssl subcommand introduced in Puppet 6. Prior to Puppet 6 there was no separate command and it required manual work. + +Assuming the Puppetserver with CA is on `foreman.example.com`, the following command can be run: + +```bash +puppet ssl bootstrap --server foreman.example.com +``` + +This will submit a CSR (Certificate Signing Request) to the Puppet CA running on foreman.example.com. There the request can be signed. + +```bash +puppetserver ca sign --certname host.example.com +``` + +CSRs also show up in the Foreman interface and can be signed there as well. + +#### Standalone Puppetserver + +A standalone Puppetserver can be configured along with a smart proxy installation, enabling the Puppet infrastructure to be scaled out. This assumes the SSL certificates have been bootstrapped. + +Command line arguments: + +{% highlight bash %} +foreman-installer \ + --no-enable-foreman \ + --no-enable-foreman-plugin-puppet \ + --no-enable-foreman-cli \ + --no-enable-foreman-cli-puppet \ + --enable-puppet \ + --puppet-server-ca=false \ + --enable-foreman-proxy \ + --foreman-proxy-puppetca=false \ + --foreman-proxy-foreman-base-url=https://foreman.example.com \ + --foreman-proxy-trusted-hosts=foreman.example.com \ + --foreman-proxy-oauth-consumer-key= \ + --foreman-proxy-oauth-consumer-secret= +{% endhighlight %} + +Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from your Foreman server, using: `sudo foreman-rake config | grep oauth_consumer`, and set the Foreman URLs appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with `--foreman-proxy-register-in-foreman=false`. + +#### PuppetDB integration + +An existing PuppetDB server can be integrated into a Puppetserver by adding: + +{% highlight bash %} +foreman-installer \ + [...] + --puppet-server-puppetdb-host=puppetdb.example.com \ + --puppet-server-reports=foreman,puppetdb \ + --puppet-server-storeconfigs-backend=puppetdb +{% endhighlight %} + +Be aware that foreman-installer does not setup the PuppetDB server itself. Only setups using Puppet's Puppet AIO packages are supported for PuppetDB integration using these parameters. + +#### Foreman server without the Puppetserver + +The default "all-in-one" Foreman installation includes a Puppetserver, but this can be disabled. Foreman by default uses Puppet's SSL certificates however, so the certificates must be bootstrapped. + +Command line arguments: + +{% highlight bash %} +foreman-installer \ + --puppet-server=false \ + --foreman-proxy-puppet=false \ + --foreman-proxy-puppetca=false +{% endhighlight %} + +This will still configure the Puppet agent, but this too can be disabled with `--no-enable-puppet` to disable the whole Puppet module. + +#### Smart proxy for DNS, DHCP etc. + +The smart proxy allows management of various network services, such as DNS, DHCP and TFTP. The installer can set up a basic smart proxy service ready to be configured, or it can install and configure BIND or ISC DHCP ready to go. A certificate should be generated and copied to the host first so Foreman can contact the proxy server. + +Command line arguments for a basic smart proxy installation: + +{% highlight bash %} +foreman-installer \ + --no-enable-foreman \ + --no-enable-foreman-puppet \ + --no-enable-foreman-cli \ + --no-enable-foreman-cli-puppet \ + --no-enable-puppet \ + --enable-foreman-proxy \ + --foreman-proxy-foreman-base-url=https://foreman.example.com \ + --foreman-proxy-trusted-hosts=foreman.example.com \ + --foreman-proxy-oauth-consumer-key= \ + --foreman-proxy-oauth-consumer-secret= +{% endhighlight %} + +Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from your Foreman server, using: `sudo foreman-rake config | grep oauth_consumer`, and set the Foreman URLs appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with `--foreman-proxy-register-in-foreman=false`. + +Command line arguments for a smart proxy configured with just TFTP, BIND, setting DNS forwarders and overriding the default forward and reverse DNS zones: + +{% highlight bash %} +foreman-installer \ + --no-enable-foreman \ + --no-enable-foreman-puppet \ + --no-enable-foreman-cli \ + --no-enable-foreman-cli-puppet \ + --no-enable-puppet \ + --enable-foreman-proxy \ + --foreman-proxy-tftp=true \ + --foreman-proxy-puppet=false \ + --foreman-proxy-puppetca=false \ + --foreman-proxy-dns=true \ + --foreman-proxy-dns-interface=eth0 \ + --foreman-proxy-dns-zone=example.com \ + --foreman-proxy-dns-reverse=0.0.10.in-addr.arpa \ + --foreman-proxy-dns-forwarders=8.8.8.8 \ + --foreman-proxy-dns-forwarders=8.8.4.4 \ + --foreman-proxy-foreman-base-url=https://foreman.example.com \ + --foreman-proxy-trusted-hosts=foreman.example.com \ + --foreman-proxy-oauth-consumer-key= \ + --foreman-proxy-oauth-consumer-secret= +{% endhighlight %} + +Ensure the dns-interface argument is updated with the correct network +interface name for the DNS server to listen on. After configuration, make sure +to create Subnet in Foreman under *Infrastructure > Subnets* for the +particular Smart Proxy which registers automatically. + +Command line arguments for a smart proxy configured with just ISC DHCP and a single DHCP subnet: + +{% highlight bash %} +foreman-installer \ + --no-enable-foreman \ + --no-enable-foreman-puppet \ + --no-enable-foreman-cli \ + --no-enable-foreman-cli-puppet \ + --no-enable-puppet \ + --enable-foreman-proxy \ + --foreman-proxy-puppet=false \ + --foreman-proxy-puppetca=false \ + --foreman-proxy-dhcp=true \ + --foreman-proxy-dhcp-interface=eth0 \ + --foreman-proxy-dhcp-gateway=10.0.0.1 \ + --foreman-proxy-dhcp-range="10.0.0.100 10.0.0.200" \ + --foreman-proxy-dhcp-nameservers="10.0.1.2,10.0.1.3" \ + --foreman-proxy-foreman-base-url=https://foreman.example.com \ + --foreman-proxy-trusted-hosts=foreman.example.com \ + --foreman-proxy-oauth-consumer-key= \ + --foreman-proxy-oauth-consumer-secret= +{% endhighlight %} + +Also ensure here that the dhcp-interface argument is updated for the interface +to run DHCP on. After configuration, make sure to create a new Subnet (or +import from existing) in the Foreman interface. + +While it is possible to define the same DHCP range in Foreman, it's usually +good practice to select a range from outside the pool defined in the +installer, but still in the subnet. For the example above, it is recommended +to define the DHCP range from 10.0.0.1 to 10.0.0.99 in the Foreman UI which +gives the following IP address distribution: + +* 10.0.0.1 - 10.0.0.99 - addresses reserved during bare-metal provisioning by Foreman +* 10.0.0.100 - 10.0.200 - addresses for dynamic clients in the subnet + (discovered hosts, unmanaged hosts) diff --git a/_includes/manuals/3.12/3.2_foreman_installer.md b/_includes/manuals/3.12/3.2_foreman_installer.md new file mode 100644 index 0000000000..648841a9b7 --- /dev/null +++ b/_includes/manuals/3.12/3.2_foreman_installer.md @@ -0,0 +1,22 @@ + +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, 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. + +It's strongly recommended to use the installer instead of only installing packages, as the installer uses OS packages and it saves a lot of time otherwise spent replicating configuration by hand. + +By default it will configure: + +* Apache HTTP with SSL (using a Puppet-signed certificate) +* Foreman running under Puma (using systemd socket activation) +* Smart Proxy with SSL (using a Puppet-signed certificate) configured for Puppet and TFTP +* Puppetserver +* Puppet agent configured + +Other modules can be enabled, which will also configure: + +* ISC DHCP server +* BIND DNS server +* TFTP server (under xinetd on Red Hat 7 platforms) + +It's recommended to run the installer on a fresh and clean single-purpose system, since the configurations of the aforementioned components is (at least partially) overwritten by the installer. diff --git a/_includes/manuals/3.12/3.3.1_rpm_packages.md b/_includes/manuals/3.12/3.3.1_rpm_packages.md new file mode 100644 index 0000000000..9a2165ae7b --- /dev/null +++ b/_includes/manuals/3.12/3.3.1_rpm_packages.md @@ -0,0 +1,66 @@ + +Foreman is packaged for the following RPM based distributions: + +* RHEL and derivatives, version 8 +* RHEL and derivatives, version 9 + +**Note:** The RPM packages are not tested on Rocky Linux or Oracle Linux. The Foreman installation on Rocky Linux or Oracle Linux may or may not work. + +For most users, it's highly recommended to use the [installer](manuals/{{page.version}}/index.html#3.2ForemanInstaller) as the packages only provide the software and a standalone Foreman service. The installer installs these packages, then additionally configures Foreman to run under Apache with PostgreSQL, plus can configure a complete Puppet setup integrated with Foreman. + +### Pre-requisites: Puppet + +It's recommended to [configure the Puppet repositories](https://puppet.com/docs/puppet/latest/install_agents.html#task-9788) to obtain the latest version of Puppet available. The version in EPEL is not supported. + +### Available repositories + +Three main repos are provided at : + +* `/client` or `/client/VERSION` (e.g. `/client/{{page.version}}`) carries packages relevant to clients. This is optional and Foreman does not require anything installed on clients. +* `/releases` or `/releases/VERSION` (e.g. `/releases/{{page.version}}`) carries the all releases and updates of Foreman and its dependencies. +* `/plugins` or `/plugins/VERSION` (e.g. `/plugins/{{page.version}}`) carries the all plugin releases. + +Under each repo are directories for each distribution, then each architecture. + +### Release packages + +To set up the repository, foreman-release packages are provided which add a repo definition to `/etc/yum.repos.d`. Install the release RPM and enable the module: + + # EL8 + dnf -y install https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm + dnf -y module enable foreman:el8 + + # EL9 + dnf -y install https://yum.theforeman.org/releases/{{page.version}}/el9/x86_64/foreman-release.rpm + +### Signing + +Release and release candidate packages are signed by the per-release key listed on [Security](security.html#GPGkeys). Nightly packages are not signed. + +### Available packages + +Install foreman and other foreman-* packages to add functionality: + + foreman Foreman server + foreman-proxy Foreman Smart Proxy + foreman-debug Log and debug collection tools + foreman-ec2 Amazon EC2 provisioning support + foreman-libvirt libvirt provisioning support + foreman-openstack OpenStack Nova provisioning support + foreman-ovirt oVirt/RHEV provisioning support + foreman-vmware VMware provisioning support + foreman-cli Foreman CLI utility + foreman-console Console additions + foreman-service A standalone service implementation + foreman-selinux SELinux targeted policy + foreman-postgresql PostgreSQL database support + +### Setup + +1. Configure by editing `/etc/foreman/settings.yaml` and `/etc/foreman/database.yml` +1. After changing the database, migrate it: `sudo -u foreman /usr/share/foreman/extras/dbmigrate` +1. Start the foreman service: `systemctl start foreman` + +### Upgrade + +See [upgrade instructions](manuals/{{page.version}}/index.html#3.6Upgradeto{{page.version}}) diff --git a/_includes/manuals/3.12/3.3.2_debian_packages.md b/_includes/manuals/3.12/3.3.2_debian_packages.md new file mode 100644 index 0000000000..9eed373032 --- /dev/null +++ b/_includes/manuals/3.12/3.3.2_debian_packages.md @@ -0,0 +1,102 @@ + +The Foreman packages should work on the following Debian-based Linux distributions: + +#### Distributions + +* Debian Linux 11 (Bullseye), amd64 +* Ubuntu Linux 20.04 LTS (Focal Fossa), amd64 +* Ubuntu Linux 22.04 LTS (Jammy Jellyfish), amd64 + +If you encounter any errors during the installation, [please file a bug report!](/contribute.html#Bugreporting) + +#### Apt Configuration + +Add one of the following lines to your */etc/apt/sources.list* (alternatively in a separate file in */etc/apt/sources.list.d/foreman.list*): + +``` +# Debian Bullseye +deb http://deb.theforeman.org/ bullseye {{page.version}} +# Ubuntu 20.04 Focal +deb http://deb.theforeman.org/ focal {{page.version}} +# Ubuntu 22.04 Jammy +deb http://deb.theforeman.org/ jammy {{page.version}} +``` + +You may also want some plugins from the plugin repo (required for the Foreman Installer): +``` +deb http://deb.theforeman.org/ plugins {{page.version}} +``` + +The public key for [secure APT](https://wiki.debian.org/SecureApt) can be downloaded [here](https://deb.theforeman.org/pubkey.gpg) + +You can add this key with: +``` +wget https://deb.theforeman.org/foreman.asc -O /etc/apt/trusted.gpg.d/foreman.asc +``` + +The key fingerprint is +``` +5B7C 3E5A 735B CB4D 6158 29DC 0BDD A991 FD7A AC8A +Foreman Automatic Signing Key (2021) +``` + +Remember to update your package lists! + +``` +apt-get update +``` + +#### Install packages + +The packages are split by gem dependencies - there are 13 packages to choose from. These are: + +Main package: + +* foreman + +Database gems: + +* foreman-postgresql + +Optional functionality: + +* foreman-console +* foreman-debug +* foreman-dynflow-sidekiq +* foreman-ec2 +* foreman-journald +* foreman-libvirt +* foreman-openstack +* foreman-ovirt +* foreman-redis +* foreman-service +* foreman-telemetry +* foreman-vmware + +Command line interface: + +* ruby-hammer-cli +* ruby-hammer-cli-foreman + +Installation instructions are: + +```bash +# Install packages (adjust additional packages as needed) +apt-get install foreman foreman-postgresql foreman-libvirt + +# Copy sample db config to /etc +cp /usr/share/foreman/config/database.yml.example /etc/foreman/database.yml + +# Review settings and DB config +vi /etc/foreman/settings.yaml /etc/foreman/database.yml + +# Perform initial DB setup +foreman-rake db:migrate +foreman-rake db:seed +``` + +The packages should auto-run db:migrate and db:seed if */etc/foreman/database.yml* exists. So the initial DB setup is only needed during first install, upgrades should just work. + +#### Upgrade + +See [upgrade instructions](manuals/{{page.version}}/index.html#3.6Upgradeto{{page.version}}) diff --git a/_includes/manuals/3.12/3.3_install_from_packages.md b/_includes/manuals/3.12/3.3_install_from_packages.md new file mode 100644 index 0000000000..9ae8058298 --- /dev/null +++ b/_includes/manuals/3.12/3.3_install_from_packages.md @@ -0,0 +1,4 @@ + +Packages are available for Red Hat and Debian-based distributions. This will install a standalone Foreman service running under Puma. + +The Puppet-based Foreman installer is recommended for most environments, instead of installing only the packages as it will perform full configuration too. diff --git a/_includes/manuals/3.12/3.4_install_from_source.md b/_includes/manuals/3.12/3.4_install_from_source.md new file mode 100644 index 0000000000..76a9233133 --- /dev/null +++ b/_includes/manuals/3.12/3.4_install_from_source.md @@ -0,0 +1,81 @@ + +Installing the latest development code: +Foreman uses Bundler to install dependencies and get up and running. This is the preferred way to get Foreman if you want to benefit from the latest improvements. By using the git repository you can also upgrade more easily. You will need to have Bundler installed manually for now (check your distribution repositories, or install it via rubygems). + +Foreman will run with the following requirements (aside from rubygem dependencies): + +* Ruby 2.7.x +* NodeJS 14 +* NPM 6.x + +You will want to make sure that you have *postgresql-devel* installed so the database +gems can install properly. Also, you would also need *gcc*, *ruby-devel*, +*libxml-devel*, *libxslt-devel*, *libvirt-devel*, *nodejs*, and *npm* packages. + +For RHEL7 or clones, you can issue the following commands to install *all* +required packages: + + yum groupinstall "Development Tools" "Development Libraries" + yum -y install gcc-c++ git ruby ruby-devel rubygems \ + libvirt-devel postgresql-devel openssl-devel \ + libxml2-devel libxslt-devel zlib-devel \ + readline-devel systemd-devel tar nodejs npm libcurl-devel + +Additionally, it is important that `config/database.yml` is set to use +the correct database in the "production" block. Rails (and subsequently +Foreman) will use these connection settings under "production" to manage +the database it uses and setup the necessary schema. + +{% highlight bash %} +git clone https://github.com/theforeman/foreman.git -b develop +cd foreman +cp config/settings.yaml.example config/settings.yaml +cp config/database.yml.example config/database.yml +gem install bundler +bundle install --without development test --path vendor +npm install +# set up database schema, precompile assets and locales +RAILS_ENV=production bundle exec rake db:migrate +RAILS_ENV=production bundle exec rake db:seed assets:precompile locale:pack webpack:compile +{% endhighlight %} + +The db:seed step will print out the default admin password, record this in order to log in later. + +In order to run Foreman you can use the following command inside your git repository: + +{% highlight bash %} +./bin/rails s -e production +{% endhighlight %} + +
This manual will recommend foreman-rake <task> to run rake tasks, however when installed from source, replace this with bundle exec rake <task> RAILS_ENV=production
+ +### Latest stable version + +to get latest "stable" version do: + +{% highlight bash %} +git clone https://github.com/theforeman/foreman.git -b {{page.version}}-stable +{% endhighlight %} + +### CLI (Hammer) + +To install hammer from git checkouts, you will just need ```rake``` installed on your system. +Clone and install CLI core + +{% highlight bash %} +$ git clone https://github.com/theforeman/hammer-cli.git +$ cd hammer-cli +$ rake install +$ cd .. +{% endhighlight %} + +and clone plugin with foreman commands + +{% highlight bash %} +$ git clone https://github.com/theforeman/hammer-cli-foreman.git +$ cd hammer-cli-foreman +$ rake install +$ cd .. +{% endhighlight %} + +You can install other hammer plugins via any of the methods mentioned above. diff --git a/_includes/manuals/3.12/3.5.1_initial_setup.md b/_includes/manuals/3.12/3.5.1_initial_setup.md new file mode 100644 index 0000000000..cacb8fbedc --- /dev/null +++ b/_includes/manuals/3.12/3.5.1_initial_setup.md @@ -0,0 +1,42 @@ + +#### Configuration + +Foreman configuration is managed from two places; a configuration file +*config/settings.yaml* and from the *SETTINGS/Foreman Settings* page. A full +description of the configuration options is given at +[foreman_configuration](manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) + +#### Database + +Foreman requires a database of its own to operate - database sharing is +unsupported. +PostgreSQL is the only database that is considered supported for production use. +The installer can set this up for you. + +In all cases, please use the *production* settings. + +to initialize the database schema and content, run: +``` +foreman-rake db:migrate +foreman-rake db:seed +``` + +For more information please see the database configuration page +[here](manuals/{{page.version}}/index.html#3.5.3DatabaseSetup) + +#### Import Data from Puppet + +At this point, you might want to go through the [[FAQ]] to see how can you import your data into Foreman. + +#### Start The Web Server + +if you installed via rpm, just start the foreman service, or start the builtin web server by typing: +``` +RAILS_ENV=production rails server +``` + +and point your browser to `http://foreman:3000` + +#### Getting your Puppet Reports into Foreman + +Read [Puppet_Reports](manuals/{{page.version}}/index.html#3.5.4PuppetReports) to learn how to get your nodes to report to Foreman. diff --git a/_includes/manuals/3.12/3.5.2_configuration_options.md b/_includes/manuals/3.12/3.5.2_configuration_options.md new file mode 100644 index 0000000000..91b01a8eae --- /dev/null +++ b/_includes/manuals/3.12/3.5.2_configuration_options.md @@ -0,0 +1,486 @@ + +Configuration is broken into two parts. The */etc/foreman/settings.yaml* file and the *Administer > Settings* page. The configuration file contains a few low-level options that need to be set before Foreman starts but the majority of Foreman customization is managed from within the web interface on the *Settings* page. + +The configuration file can also override those settings specified in the web interface. Any settings added in the config file that are available in the web interface will be made read-only. + +#### The config/settings.yaml file + +##### YAML start + +The first non-comment line of this file must be three dashes. + +```yaml +--- +``` + +##### require_ssl + +This boolean option configures whether Foreman insists on using only https/ssl encrypted communication channels in the web interface. This does not configure the channels used to contact the smart-proxies. Note that certain operations will still accept a http connection even if this is set, for example, the downloading of a finish script. + +```yaml +:require_ssl: true +``` + +##### support_jsonp + +This boolean options configures whether Foreman will provide support for the JavaScript object notation with padding. When set to _true_ then Foreman will allow to pass a callback parameter to the API calls. + +```yaml +:support_jsonp: false +``` + +##### trusted_proxies + +This setting configures Rails' [ActionDispatch::RemoteIp middleware](https://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html). This is for secure handling of the `X-Forwarded-For` header that HTTP proxies send. Note that some Foreman Proxy features behave as an HTTP proxy (most notably Templates), but it can also be a classical reverse proxy such as Apache. + +This should list the IP addresses or IP ranges that can send the `X-Fowarded-For` header. Implicitly this means they can spoof the request IP addresses so only set this if you use a reverse HTTP proxy and on trusted values. Being too broad can introduce security risks. + +If you use a reverse proxy in front of Puma (as the installer does by default), be sure to include localhost IPs. + +```yaml +:trusted_proxies: + - 127.0.0.0/8 + - ::1 +``` + +##### logging + +This options contains a hash of parameters that override the current logging configuration. It supports any of the options that are in `logging.yaml` (see below), but most usually it's used to change the log level for debugging. + +```yaml +:logging: + :level: debug +``` + +##### loggers + +This options contains a hash of config options for specific loggers, which cover parts of Foreman functionality. It's usually used to enable additional types of logging. + +Available loggers are: + +* app - web requests and all general application logs (default: true) +* audit - additional fact import statistics, numbers of facts added/updated/removed (default: true) +* ldap - high level LDAP queries (e.g. find users in group) and LDAP operations performed (default: false) +* permissions - evaluation of user roles, filters and permissions when loading pages (default: false) +* sql - SQL queries made through Rails ActiveRecord, only debug (default: false) + +Uncomment or add a :loggers block to enable or disable loggers: + +```yaml +:loggers: + :app: + :enabled: true + :ldap: + :enabled: false + :permissions: + :enabled: false + :sql: + :enabled: false +``` + +Some plugins may add their own loggers. See the configuration files in /etc/foreman/plugins/ which should list possibilities and enable them there. + +#### The 'logging.yaml' file + +This settings file can be found at `/etc/foreman/logging.yaml`, or `config/logging.yaml` on a source installation. It controls the default logging locations, formatting and log levels per Rails environment. + +In a normal installation, only the "production" environment is relevant - development and test are only used in source installations. The file has comments for the most common configuration options, which can be changed here or overridden from the `logging` directive in the main `settings.yaml` config file (see above). + +#### The 'Administer/Settings' page + +##### access_unattended_without_build + +When enabled, unattended URLs used to fetch templates for individual hosts will be accessible irrespective of the host build state. When disabled, the unattended URLs will only function in build mode to prevent accidental rebuilding etc. +Default: false + +##### administrator + +When Foreman needs to mail the administrator then this is the email address that it will contact. The domain is determined from Facter, else it will default to the ":domain" setting in /etc/foreman/settings.yaml. +Default: root@<your domain>. + +##### always_show_configuration_status + +When reporting the configuration status of hosts, usually only hosts with outdated reports, or a Puppet proxy/master set and no reports will be considered out of sync. When true, all hosts will be considered out of sync until a report is received. This setting should be enabled in environments where Foreman is used for reporting without smart proxies. +Default: false + +##### authorize_login_delegation + +mod_proxy and other load balancers will set a REMOTE_USER environment variable. If this is _true_ , your users will be able to login through an external service and Foreman requests will be authenticated using this REMOTE_USER variable. +Default: false + +##### authorize_login_delegation_api + +Same as above, but this setting allows REMOTE_USER authentication for API calls as well. +Default: false + +##### authorize_login_delegation_auth_source_user_autocreate + +If you have authorize_login_delegation set, new users can be autocreated through your external authentication mechanism by changing this to the name of the Auth Source you want to use to auto create users. +Default: '' + +##### bmc_credentials_accessible + +By default, all BMC passwords will be redacted in template and ENC output, preventing both users from viewing the passwords directly and also from configuration (or access) in Puppet and other config management tools using the ENC interface. Foreman will continue to use the stored password for BMC power operations. + +When set to true, all passwords stored on BMC network interfaces will be visible to other users who can view the host via the ENC YAML preview and accessible through templates, for the purposes of configuring BMC interfaces automatically. + +Note that setting this to false also this requires that `safemode_render` be enabled, else it could be bypassed. + +Default: false + +##### clean_up_failed_deployment + +During host provisioning onto a compute resource using images or templates and a finish script, this setting controls the behavior of Foreman when the script fails. When true, the new host and virtual machine (on the compute resource) will be deleted if the script fails. When false, the host and virtual machine are left running so the script can be debugged. +Default: true + +##### create_new_host_when_facts_are_uploaded + +When facts are received from Puppet or other configuration management systems, a corresponding host will be created in Foreman if the certname or hostname is unknown. When false, this behavior is disabled and facts will be discarded from unknown hosts. +Default: true +See also: create_new_host_when_report_is_uploaded + +##### create_new_host_when_report_is_uploaded + +If a report is received from Puppet or other configuration management systems, a corresponding host will be created in Foreman if the hostname is unknown. When false, this behavior is disabled and reports will be discarded from unknown hosts. +Default: true +See also: create_new_host_when_facts_are_uploaded + +##### db_pending_seed +When you upgrade Foreman using foreman-installer, the new version may contain some seed data such as operating systems, provisioning templates, roles and more. It will also update any previous seeded data. If this is true, the next run of the installer will seed this data. If it is false, the database will not get this seeded data. + +Default: true + +##### default_locale +Specifies, which language is set for newly created users. This also applies to new users managed via LDAP. + +Default: '', but 'Browser language' is used for newly created users. This also applies to new users managed via LDAP. + +##### default_timezone +Specifies, which timezone is set for newly created users. + +Default: '', but 'Browser timezone' is used for newly created users. + +##### default_location + +The name of an location that hosts uploading facts into Foreman will be assigned to if they are new or missing an location. This can be used when hosts are created through fact uploads to ensure they're assigned to the correct location to prevent resource mismatches. For inherited location, the fact should use slash-delimited names, e.g. "USA/New York". +Default: '', but initialized by the database seed to the initially seeded location + +##### default_organization + +The name of an organization that hosts uploading facts into Foreman will be assigned to if they are new or missing an organization. This can be used when hosts are created through fact uploads to ensure they're assigned to the correct organization to prevent resource mismatches. For inherited organization, the fact should use slash-delimited names, e.g. "ACME Inc/Engineering". +Default: '', but initialized by the database seed to the initially seeded organization + +##### delivery_method + +The method for sending emails from the Foreman instance, either _sendmail_ (running the command set by _sendmail_location_) to send mail via the configured local MTA, or _smtp_ for direct connection to an outbound SMTP server (given by settings with the _smtp_ prefix). +Default: sendmail + +##### email_reply_address + +The return address applied to outgoing emails. +Default: Foreman-noreply@<your domain> + +##### email_subject_prefix + +The subject line prefix for any emails sent by Foreman. +Default: [foreman] + +##### entries_per_page + +The number of entries that will be shown in the web interface for list operations. +Default: 20 + +##### foreman_url + +Emails may contain embedded references to Foreman's web interface. This option allows the URL prefix to be configured. The FQDN is determined from Facter, else it will default to the ":fqdn" setting in /etc/foreman/settings.yaml. +Default: https://FQDN/ or http://FQDN/ (depending on require_ssl) +See also: unattended_url + +##### global_(PXELinux/PXEGrub/PXEGrub2) +Default PXELinux/PXEGrub/PXEGrub2 template. This template gets deployed to all configured TFTP servers. For example, this template can be used to make new hosts in a network boot into [Foreman Discovery](http://theforeman.org/plugins/foreman_discovery/). +* Default: none + +##### matchers_inheritance + +Matchers used in smart variables or smart class parameters to match host groups, organizations or locations can be inherited by children too (e.g. a matcher for hostgroup=Base will also apply to Base/Web). Set this to false to make matchers only match a particular hostgroup, organization or location and not its children. +Default: true + +##### host_power_status + +Controls whether the power status of hosts is shown on the hosts list, which may lead to decreased performance, or if the column is removed. +Default: true + +##### host_owner + +Defines which is the default owner of newly provisioned hosts. It can be either a user or a user group. If unset, the default owner of the host will be the user who created the host. +Default: none + +##### idle_timeout + +Users that stay idle (no requests sent to Foreman) for more than this number of minutes will be logged out. +Default: 60 + +##### interpolate_erb_in_parameters + +If _true_, Foreman variables will be exposed to the ENC. Check [Template Writing Reference](https://docs.theforeman.org/{{ page.version }}/Managing_Hosts/index-foreman-el.html#Template_Writing_Reference_managing-hosts) for a more comprehensive guide on how to create and use these variables in your ERB templates. +Default: true + +##### ignore_facts_for_operatingsystem + +When Foreman receives facts for a host (from any source, Puppet, Ansible...) it will try to update the operating system to whatever the incoming facts say. This setting allows you to import all facts but ignore those related with operating system. If this is set to _true_, Foreman will update the operating system of hosts using these facts. +Default: false +See also: ignored_facts_for_domain + +##### ignore_facts_for_domain + +See ignored_facts_for_operatingsystem - this setting is the equivalent for domains. +Default: false + +##### ignore_puppet_facts_for_provisioning + +If this option is set to _true_ then Foreman will not update the IP and MAC addresses stored on a host's network interfaces with the values that it receives from facts. It will also include Foreman's values for IP and MAC to Puppet in its node/ENC information. +Default: false +See also: ignored_interface_identifiers + +##### ignored_interface_identifiers + +When importing facts and updating stored information on network interfaces, any network interface with an identifier (e.g. `eth0`) that matches any of the items in this list will be ignored and not updated. This can be used to avoid updating special types of interfaces when Foreman has limited or no understanding of them. The contents are an array of strings which may contain `*` wildcards to match zero or more characters. +Default: `["lo", "en*v*", "usb*", "vnet*", "macvtap*", ";vdsmdummy;", "veth*", "docker*", "tap*", "qbr*", "qvb*", "qvo*", "qr-*", "qg-*", "vlinuxbr*", "vovsbr*", "br-int", "vif*", "cali*"]` +See also: ignore_puppet_facts_for_provisioning + +##### libvirt_default_console_access + +The IP address that should be used for the console listen address when provisioning new virtual machines via Libvirt. +Default: 0.0.0.0 + +##### location_fact + +The name of a fact from hosts reporting into Foreman which gives the full location name of the host. This can be used when hosts are created through fact uploads to ensure they're assigned to the correct location to prevent resource mismatches. The location of a host will be updated to the value of the fact on every fact upload. For inherited locations, the fact should use slash-delimited names, e.g. "USA/New York". +Default: foreman_location + +##### local_boot_(PXELinux/PXEGrub/PXEGrub2) +When creating hosts that use a PXE loader, this will be the default template for local boot. +* Default: none + +##### login_delegation_logout_url + +If your external authentication system has a logout URL, redirect your users to it here. This setting can be useful if your users sign in Foreman through SSO, and you want them to sign out from all services when they log out Foreman. +Default: '' + +##### login_text + +Text to be displayted in the login-page footer. The keyword `$VERSION` is replaced by the current version. + +Default: `Version $VERSION` + +##### manage_puppetca + +If this option is set to _true_ then Foreman will manage a host's Puppet certificate signing. If it is set to _false_ then some external mechanism is required to ensure that the host's certificate request is signed. +Default: true + +##### name_generator_type + +Specifies the method used to generate random hostnames when creating a new host, either _Random-based_, _MAC-based_ for bare metal hosts only, or _Off_ to disable the function and leave the field blank. +Default: _Random-based_ + +##### oauth_active + +Enables OAuth authentication for API requests. +Default: false + +##### oauth_consumer_key + +OAuth consumer key +Default: none + +##### oauth_consumer_secret + +OAuth consumer secret +Default: none + +##### oauth_map_users + +This allows OAuth users to specify which user their requests map to. When this is _false_, OAuth requests will map to admin. +Default: true + +##### organization_fact + +The name of a fact from hosts reporting into Foreman which gives the full organization name of the host. This can be used when hosts are created through fact uploads to ensure they're assigned to the correct organization to prevent resource mismatches. The organization of a host will be updated to the value of the fact on every fact upload. For inherited organization, the fact should use slash-delimited names, e.g. "ACME Inc/Engineering". +Default: foreman_organization + +##### outofsync_interval + +Duration in minutes after which servers classed as out of sync, if the report origin has not been identified. +Default: 30 + +##### proxy_request_timeout + +Timeout in seconds used when making REST requests to a Smart Proxy, e.g. when importing Puppet classes or creating DHCP records. May be set to a larger value when certain operations take a long time. +Default: 60 + +##### query_local_nameservers + +If _true_, Foreman will query the local DNS. When _false_ Foreman will query the SOA/NS authority. Warning! Querying a resolver can cause Foreman to get false positives when checking presence of DNS records due to caching. +Default: false +See also: dns_conflict_timeout + +##### restrict_registered_smart_proxies + +When set to _true_, services such as Puppet servers (or Salt) need to have a smart proxy registered with the appropriate feature (e.g. Puppet) to access fact/report importers and ENC output. +Default: true + +##### root_pass + +If a root password is not provided whilst configuring a host or its host group then this encrypted password is used when building the host. +Default: '' +(To generate a new one you should use: *openssl passwd -1 "your_password"* ) + + +##### safemode_render + +In the default configuration with `safemode_render` set to _true_, access to variables, Foreman internals and any object that is not whitelisted within Foreman will be denied for system security. + +When set to _false_, any object may be accessed by a user with permission to use templating features, either via editing of templates, parameters or smart variables. This permits users full remote code execution _on the Foreman server_, effectively disabling all authorization if set to _false_. It is strongly recommended for this setting to be _true_ in most environments. + +Default: true + +##### send_welcome_email + +New account holders will receive a welcome email when the account is created if this is enabled, including their username and a link to Foreman. +Default: false + +##### sendmail_arguments + +Arguments given to the sendmail command when sending emails from Foreman. +Default: `-i` + +##### sendmail_location + +Path to the sendmail binary, or other sendmail-compatible MTA for outbound email. +Default: `/usr/sbin/sendmail` + +##### smtp_address + +Outbound SMTP connections will connect to the SMTP server at this address, either a hostname or IP address. +Default: _empty value_ (implying localhost) + +##### smtp_authentication + +Outbound SMTP connections will authenticate to the SMTP server using the protocol specified here, either: _plain_ for the PLAIN SMTP mechanism (plain text), _login_ for the LOGIN SMTP mechanism (plain text), _cram-md5_ for the CRAM-MD5 method (hashed, not plain text), or _none_ to disable authentication. See also: _smtp_username_, _smtp_password_. +Default: none + +##### smtp_domain + +Outbound SMTP connections will use this domain to identify during the HELO/EHLO command. +Default: _empty value_ + +##### smtp_enable_starttls_auto + +Outbound SMTP connections will automatically switch to TLS mode (via `STARTTLS`) when the capability is advertised by the SMTP server. This implies verification of TLS/SSL certificates by default (see also: _smtp_openssl_verify_mode_). +Default: true + +##### smtp_openssl_verify_mode + +Outbound SMTP connections to a TLS-enabled SMTP server will verify the remote server certificate according to this setting. Either the default (usually _peer_), _none_ for no verification of the server certificate, or _peer_ for explicitly verifying the server certificate. _client_once_ and _fail_if_no_peer_cert_ have no effect in outbound SMTP connections. +Default: Default verification mode (usually _peer_) + +##### smtp_password + +Outbound SMTP connections with authentication enabled will authenticate with this password (see also: _smtp_username_, _smtp_authentication_). +Default: _empty value_ + +##### smtp_port + +Outbound SMTP connections will connect to the SMTP server on this TCP port. Some SMTP servers may prefer port 587 for email submission. +Default: 25 + +##### smtp_username + +Outbound SMTP connections with authentication enabled will identify with this username (see also: _smtp_password_, _smtp_authentication_). +Default: _empty value_ + +##### ssl_client_cert_env + +Environment variable containing the entire PEM-encoded certificate from the client. This environment variable is required when authenticating using Subject Alternative Names and will be preferred over `ssl_client_dn_env` if available. Under Apache HTTP and mod_ssl, `SSLOptions +ExportCertData` sets this environment variable. +Default: SSL_CLIENT_CERT +See also: ssl_client_dn_env + +##### ssl_client_dn_env + +Environment variable containing the subject DN from a client SSL certificate. Under Apache HTTP and mod_ssl, `SSLOptions +StdEnvVars` sets this environment variable. +Default: SSL_CLIENT_S_DN +See also: ssl_client_cert_env + +##### ssl_client_verify_env + +Environment variable containing the verification status of a client SSL certificate +Default: SSL_CLIENT_VERIFY + +##### ssl_ca_file + +The SSL Certificate Authority file that Foreman will use when connecting to its smart-proxies. +Default: The CA file used by puppet + +##### ssl_certificate + +The SSL certificate that Foreman will use when connecting to its smart-proxies. +Default: The host certificate used by puppet + +##### ssl_priv_key + +The SSL private key file that Foreman will use when connecting to its smart-proxies. +Default: The private key file used by puppet + +##### token_duration + +Time in minutes installation tokens should be valid for, 0 to disable token generation. +Default: 360 (6 hours) + +##### trusted_hosts + +Other trusted hosts in addition to Smart Proxies allowed to access fact/report importers and ENC output. i.e: [puppetserver1.yourdomain.com, puppetserver2.yourdomain.com] +Default: [] + +##### unattended_url + +This controls the URL prefix used in provisioning templates such as TFTP/PXELinux files that refer to the Foreman server. It is usually HTTP rather than HTTPS due to lack of installer support for HTTPS. The FQDN is determined from Facter, else it will default to the ":fqdn" setting in /etc/foreman/settings.yaml. +Default: http://FQDN/ +See also: foreman_url + +##### update_environment_from_facts + +If Foreman receives an environment fact from one of its hosts and if this option is _true_, it will update the host's environment with the new value. By default this is not the case as Foreman should manage the host's environment. +Default: false + +##### update_ip_from_built_request + +If _true_, Foreman will update the host IP with the IP that made the 'build' request. This request is made at the end of a provisioning cycle to indicate a host has completed the build. +Default: false + +##### update_subnets_from_facts + +If _true_, fact imports from Puppet and other config management tools will update the subnet on host network interfaces to match the IP address given in facts, preventing a mismatch. +Default: false + +##### use_shortname_for_vms + +When false, any hosts created on a compute resource will use the FQDN of the host for the name of the virtual machine. When set to the true, the short name (i.e. without domain) will be used instead. +Default: false + +##### use_uuid_for_certificates + +When enabled, Foreman will generate UUIDs for each host instead of using the hostname as the Puppet certname, which is more reliable with changing hostnames. Note that when disabling this setting, existing stored certnames won't be changed or discarded until new certificates are requested from a host (i.e. on a rebuild), in order that the existing certificate remains known to Foreman and can be revoked. + +##### websockets_encrypt + +When enabled, virtual machine consoles using NoVNC will always be sent over an encrypted WebSocket connection. Requires both `websockets_ssl_cert` and `websockets_ssl_key` to be configured too. +Default: true if `require_ssl` is enabled +See also: websockets_ssl_cert, websockets_ssl_key + +##### websockets_ssl_cert + +Path to the SSL certificate that will be used for the WebSockets server when serving virtual machine consoles. Should be the same as the SSL certificate used for the Foreman web server (e.g. Apache). + +##### websockets_ssl_key + +Path to the SSL private key that will be used for the WebSockets server when serving virtual machine consoles. Should be the same as the SSL key used for the Foreman web server (e.g. Apache). diff --git a/_includes/manuals/3.12/3.5.3_database_setup.md b/_includes/manuals/3.12/3.5.3_database_setup.md new file mode 100644 index 0000000000..515fe42874 --- /dev/null +++ b/_includes/manuals/3.12/3.5.3_database_setup.md @@ -0,0 +1,18 @@ + +Foreman is a Rails application. While Rails supports different databases, Foreman supports only PostgreSQL for production deployments. + +The database configuration file can be found at: + +`/etc/foreman/database.yml` + +
When using PostgreSQL, you should make sure that the foreman-postgresql package is installed. See 3.3 Install From Packages.
+ +Edit your config/database.yml and modify: +```yaml +production: + adapter: postgresql + database: foreman + username: foreman + password: password + host: localhost +``` diff --git a/_includes/manuals/3.12/3.5.4_puppet_reports.md b/_includes/manuals/3.12/3.5.4_puppet_reports.md new file mode 100644 index 0000000000..02f4911316 --- /dev/null +++ b/_includes/manuals/3.12/3.5.4_puppet_reports.md @@ -0,0 +1,82 @@ + +Foreman uses a custom puppet reports address (similar to tagmail or store) which Puppet will use to upload its report into Foreman. This enables you to see the reports through the web interface as soon as the client finishes its run. + +#### Configuration + +##### Client + +Ensure that the puppet clients has the following option in their puppet.conf: +```ini +report = true +``` + +Without it, no reports will be sent. + +##### Puppet server + +First identify the directory containing report processors, e.g. + +* AIO installations: /opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/reports/ +* Fedora: /usr/share/ruby/vendor_ruby/puppet/reports/ +* Debian or Ubuntu: /usr/lib/ruby/vendor_ruby/puppet/reports/ +* other OSes, look for tagmail.rb in the Puppet installation (`locate tagmail.rb`) + +Copy [the report processor source](https://raw.githubusercontent.com/theforeman/puppet-puppetserver_foreman/master/files/report.rb) to this report directory and name it `foreman.rb`. + +Create a new configuration file at `/etc/puppetlabs/puppet/foreman.yaml` (Puppet 4 AIO) or `/etc/puppet/foreman.yaml` (non-AIO) containing: +```yaml +--- +# Update for your Foreman and Puppet server hostname(s) +:url: "https://foreman.example.com" +:ssl_ca: "/etc/puppetlabs/puppet/ssl/certs/ca.pem" +:ssl_cert: "/etc/puppetlabs/puppet/ssl/certs/puppet.example.com.pem" +:ssl_key: "/etc/puppetlabs/puppet/ssl/private_keys/puppet.example.com.pem" + +# Advanced settings +:puppetdir: "/opt/puppetlabs/server/data/puppetserver" +:puppetuser: "puppet" +:facts: true +:timeout: 10 +:threads: null +``` + +Edit the URL field to point to your Foreman instance, and the SSL fields for the hostname of the Puppet server (which may be the same host). Paths to Puppet's SSL certificates will be under /var/lib/puppet/ssl/ when using Puppet with non-AIO. + +Lastly add this report processor to your Puppet server configuration. In your server puppet.conf under the `[main]` section add: + +```ini +reports=log, foreman +``` + +and restart your Puppet server. + +You should start seeing reports coming in under the reports link. + +##### Debugging reports + +If reports aren't showing up in Foreman when an agent is run, there can be a number of reasons. First check through the above configuration steps, and then look at these places to narrow down the cause: + +1. Puppetserver logs may show an issue either loading or executing the report processor. Check syslog (/var/log/messages or syslog) for `puppetserver` messages, or /var/log/puppetlabs/puppetserver/. +1. /var/log/foreman/production.log should show a `POST "/api/reports"` request each time a report is received, and will end in `Completed 201 Created` when successful. Check for errors within the block of log messages. +1. When viewing reports in Foreman's UI, be aware that the default search is for "eventful" reports. Clear the search ('x') to see reports with no changes. + +#### Expire reports automatically + +You will probably want to delete your reports after some time to limit database growth. To do so, you can set a cronjob: + +Available conditions: + +* days => number of days to keep reports (defaults to 7) +* status => status of the report (defaults to 0 --> "reports with no errors") + +To expires all reports regardless of their status: + +``` +foreman-rake reports:expire days=7 +``` + +To expire all non-interesting reports after one day: + +``` +foreman-rake reports:expire days=1 status=0 +``` diff --git a/_includes/manuals/3.12/3.5.5_facts_and_the_enc.md b/_includes/manuals/3.12/3.5.5_facts_and_the_enc.md new file mode 100644 index 0000000000..7f0dc5f996 --- /dev/null +++ b/_includes/manuals/3.12/3.5.5_facts_and_the_enc.md @@ -0,0 +1,156 @@ + +Foreman can act as a classifier to Puppet through the External Nodes interface. This is a mechanism provided by Puppet to ask for configuration data from an external service, via a script on the Puppet server. + +The external nodes script we supply also deals with uploading facts from hosts to Foreman, so we will discuss the two things together. + +#### Configuration + +##### Puppet server + +Download [the ENC script](https://raw.githubusercontent.com/theforeman/puppet-puppetserver_foreman/master/files/enc.rb) to `/etc/puppetlabs/puppet/node.rb` (Puppet AIO) or `/etc/puppet/node.rb` (non-AIO). The name is arbitrary, but must match configuration below, and ensure it's executable by "puppet" with `chmod +x /etc/puppet/node.rb`. + +Unless it already exists from setting up reporting, create a new configuration file at `/etc/puppetlabs/puppet/foreman.yaml` (Puppet AIO) or `/etc/puppet/foreman.yaml` (non-AIO) containing + +```yaml +--- +# Update for your Foreman and Puppet server hostname(s) +:url: "https://foreman.example.com" +:ssl_ca: "/etc/puppetlabs/puppet/ssl/certs/ca.pem" +:ssl_cert: "/etc/puppetlabs/puppet/ssl/certs/puppet.example.com.pem" +:ssl_key: "/etc/puppetlabs/puppet/ssl/private_keys/puppet.example.com.pem" + +# Advanced settings +:puppetdir: "/opt/puppetlabs/server/data/puppetserver" +:puppetuser: "puppet" +:facts: true +:timeout: 10 +:threads: null +``` + +Edit the URL field to point to your Foreman instance, and the SSL fields for the hostname of the Puppet server (which may be the same host). Paths to Puppet's SSL certificates will be under /var/lib/puppet/ssl/ and puppetdir will be under /var/lib/puppet when using Puppet with non-AIO. More information on SSL certificates is at [Securing communications with SSL](/manuals/{{page.version}}/index.html#5.4SecuringCommunicationswithSSL). + +Add the following lines to the [master] section of puppet.conf: + +```ini +[master] + external_nodes = /etc/puppetlabs/puppet/node.rb + node_terminus = exec +``` + +Restart the Puppet server. When the next agent checks in, the script will upload +fact data for this host to Foreman, and download the ENC data. + +The `--no-environment` option can be optionally specified to stop the ENC from +being authoritative about the agent's Puppet environment. This can be useful +in development setups where the agent may be run against different +environments. + +##### Client + +No agent configuration is necessary to use this functionality. + +##### Testing the config + +Make sure that the puppet user can execute the ENC script and it works: + +``` +sudo -u puppet /etc/puppet/node.rb [the name of a node, eg agent.local] +``` + +should output something like: + +```yaml +parameters: + puppetmaster: puppet + foreman_env: &id001 production +classes: + helloworld: +environment: *id001 +``` + +This output should match the information displayed when you click on the YAML button +on the Host page in Foreman. + +For further information see the [Puppet Labs docs on external nodes](https://puppet.com/docs/puppet/latest/nodes_external.html) + +##### Debugging the ENC + +1. If Puppet agents receive empty catalogs, check the puppet.conf master configuration has the ENC script configured. Also check the output of the ENC for the hostname logged by Puppet (which may be different) to see if Foreman is reporting the correct configuration. +1. If the hostname.yaml facts file is missing, this is typically a Puppet misconfiguration. +1. Failures to upload facts or download the ENC data may be a network issue (check the URL and SSL settings) or an error on the Foreman server. Check /var/log/foreman/production.log for two requests, `POST "/api/hosts/facts"` and `GET "/node/client.example.com?format=yml"` and for any errors within the block of log messages. + +#### Assigning data to hosts through the ENC + +Foreman passes all associated parameters, classes,and class parameters, to the Host, +including those inherited from host groups, domains, or global settings. See section +[Managing Puppet](/manuals/{{page.version}}/index.html#4.2ManagingPuppet) for +more information on assigning configuration to hosts. + +#### Creating hosts in Foreman with facts + +By default, Foreman adds hosts to its database that it learns about through facts, +provided the "create_new_host_when_facts_are_uploaded" setting is enabled. + +Locations and organizations can be inferred from the "foreman_location" or +"foreman_organization" facts as supplied by the host. The +names of these facts can be changed with the "location_fact" and +"organization_fact" settings respectively. Foreman will update hosts on each +fact upload based on the value of these facts. + +If these facts aren't supplied, then the "default_location" and +"default_organization" settings can be used to set values globally when a +host doesn't have a location or an organization set. + +More information in the [Configuration](/manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) +section. + +#### Pushing facts to Foreman when not using the ENC functionality + +There are several options for pushing fact data to Foreman if you are using Foreman +for reporting/inventory only. + +##### Using node.rb + +The ENC script (node.rb) accepts an option to run in 'batch-mode'. In this mode, +the script iterates over the cached fact data stored on the Puppet server, and uploads +all of it to Foreman. + +Download and configure the node.rb script as above, and then call it like this: + +``` +sudo -u puppet /etc/puppetlabs/puppet/node.rb --push-facts +``` + +The following options are available for node.rb's batch mode: + +* `--push-facts` uploads all facts sequentially which have changed since the + last run. +* `--push-facts-parallel` uploads all facts in parallel which have changed since + the last run. The number of threads is specified by the :threads setting or + the number of processors. +* `--watch-facts` runs in the foreground and upload facts based on inotify + events, used in conjunction with either --push-facts option. + +##### Direct HTTP upload + +Foreman's fact-upload API endpoint accepts data in pure JSON. You can push data +to Foreman as a hash containing: + +```json +{ + "name": "fqdn-of-host.domain.com", + "certname": "optional-certname-of-host.domain.com", + "facts": { + "fact1": "string", + "fact2": "true", + "fact3": "1.2.3.4", + ... + } +} +``` + +The 'certname' is optional but will be used to locate the Host in Foreman when +supplied. See [the API documentation](/api/{{page.version}}/apidoc/v2/hosts/facts.html) for more details. + +This body can be POSTed to '/api/hosts/facts' using Foreman API v2. See the +[node.rb template](https://raw.githubusercontent.com/theforeman/puppet-puppetserver_foreman/master/files/enc.rb) for an example of constructing and sending data in Ruby. diff --git a/_includes/manuals/3.12/3.5.6_cli.md b/_includes/manuals/3.12/3.5.6_cli.md new file mode 100644 index 0000000000..a0bc4c33dd --- /dev/null +++ b/_includes/manuals/3.12/3.5.6_cli.md @@ -0,0 +1,52 @@ +The Command Line Interface is based on the [hammer](https://github.com/theforeman/hammer-cli) framework. The foreman-related commands are defined in plugin ```hammer_cli_foreman``` + +#### Format and locations + +Configuration is loaded from a set of directories in this order: + + - ```./config/hammer/``` (config dir in CWD) + - ```/etc/hammer/```. + - ```~/.hammer/``` + - custom location specified on command line - ```-c CONF_FILE_PATH``` + +In each of these directories hammer tries to load `cli_config.yml` and anything in the `cli.modules.d` subdirectory which is the recommended location for configuration of hammer modules. + +Later directories and files have precedence if they redefine the same option. Files from cli.modules.d are loaded in alphabetical order. + +Hammer uses yaml formatting for its configuration. The config file template is contained in the hammer_cli gem. + + ```bash +gem contents hammer_cli|grep cli_config.template.yml +``` +and can be copied to one of the locations above and changed as needed. The packaged version of hammer copies the template to /etc for you. + + +#### Plugins + +Plugins are disabled by default. You have to edit the config file and enable them manually under ```modules``` option, as can be seen in the sample config below. + +Plugin specific configuration should be nested under plugin's name. + +#### Options + + - ```:log_dir: ``` - directory where the logs are stored. The default is ```/var/log/hammer/``` and the log file is named ```hammer.log``` + - ```:log_level: ``` - logging level. One of ```debug```, ```info```, ```warning```, ```error```, ```fatal``` + - ```:log_owner: ``` - logfile owner + - ```:log_group: ``` - logfile group + - ```:log_size: 1048576``` - size in bytes, when exceeded the log rotates. Default is 1MB + - ```:watch_plain: false``` - turn on/off syntax highlighting of data being logged in debug mode + +#### Sample config + +```yaml +:modules: + - hammer_cli_foreman + +:foreman: + :host: 'https://localhost/' + :username: 'admin' + :password: 'changeme' + +:log_dir: '/var/log/foreman/' +:log_level: 'debug' +``` diff --git a/_includes/manuals/3.12/3.5_configuration.md b/_includes/manuals/3.12/3.5_configuration.md new file mode 100644 index 0000000000..339861b748 --- /dev/null +++ b/_includes/manuals/3.12/3.5_configuration.md @@ -0,0 +1,3 @@ + +The following sections detail the configuration steps required to get Foreman working in your environment. +Lets get started! diff --git a/_includes/manuals/3.12/3.6_upgrade.md b/_includes/manuals/3.12/3.6_upgrade.md new file mode 100644 index 0000000000..9be69877a4 --- /dev/null +++ b/_includes/manuals/3.12/3.6_upgrade.md @@ -0,0 +1,227 @@ +#### Scope + +**These instructions apply to environments not using Katello** + +If you're using the [Katello]({{ site.baseurl }}plugins/katello) content management plugin scenario, +please follow their upgrade instructions (which will also upgrade Foreman). + +#### Preparation + +**Before updating to {{page.version}}, make sure you have successfully upgraded to {{page.previous_version}} first.** + +Upgrading across more than one version is not supported, so it's required to upgrade to each +intermediate version and follow all upgrade instructions for the previous versions. + +Check the list of [Supported Platforms](manuals/{{page.version}}/index.html#3.1.1SupportedPlatforms) +when planning to upgrade, as these change between releases. If your OS is no +longer supported by Foreman, migrate or upgrade the OS (if supported) using a +release of Foreman supported by both OS versions before upgrading Foreman. + + + +To provide specific installation instructions, please select your operating system: + + +#### Step 1 - Backup + +It is recommended that you backup your database and modifications to Foreman +files(config/settings.yaml, unattended installations etc). Most upgrades are +safe but it never hurts to have a backup just in case. + +For more information about how to backup your instance head over to +[Backup](manuals/{{page.version}}/index.html#5.5.1Backup) + +#### Step 2 - Perform the upgrade + +Before proceeding, it is necessary to shutdown the Foreman instance. + +
+ No operating system selected. +
+
+{% highlight bash %} +systemctl stop httpd foreman.service foreman.socket dynflow\* +{% endhighlight %} +
+
+{% highlight bash %} +systemctl stop apache2 foreman.service foreman.socket dynflow\* +{% endhighlight %} +
+ +Now it's time to perform the actual upgrade. + +
+ No operating system selected. +
+ +
+To upgrade an existing Foreman installation, first update with the +appropriate foreman-release package: + +{% highlight bash %} +dnf upgrade https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm +{% endhighlight %} + +Clean up the yum metadata cache: + +{% highlight bash %} +dnf clean metadata +{% endhighlight %} + +If the Ruby 2.5 module was previously enabled, it must be reset: + +{% highlight bash %} +dnf -y module reset ruby +{% endhighlight %} + +Switch to the PostgreSQL 13 module: + +{% highlight bash %} +dnf -y module switch-to postgresql:13 +{% endhighlight %} + +Enable the Foreman module: + +{% highlight bash %} +dnf -y module enable foreman:el8 +{% endhighlight %} + +Next upgrade all Foreman packages: + +{% highlight bash %} +dnf upgrade ruby\* foreman\* +{% endhighlight %} +
+ +
+To upgrade an existing Foreman installation, first update with the +appropriate foreman-release package: + +{% highlight bash %} +dnf upgrade https://yum.theforeman.org/releases/{{page.version}}/el9/x86_64/foreman-release.rpm +{% endhighlight %} + +Clean up the yum metadata cache: + +{% highlight bash %} +dnf clean metadata +{% endhighlight %} + +Next upgrade all Foreman packages: + +{% highlight bash %} +dnf upgrade ruby\* foreman\* +{% endhighlight %} +
+ +
+Upgrading from the last release to {{page.version}} has been tested. Updating +the packages will upgrade the application and automatically migrate the +database. + +First edit `/etc/apt/sources.list.d/foreman.list` and change the release +number from the previous release to `{{ page.version }}`: + +
+{% highlight bash %} +deb http://deb.theforeman.org/ bullseye {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
+
+{% highlight bash %} +deb http://deb.theforeman.org/ focal {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
+
+{% highlight bash %} +deb http://deb.theforeman.org/ jammy {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
+ +Next upgrade all Foreman packages: + +{% highlight bash %} +apt-get update +apt-get --only-upgrade install ruby\* foreman\* +{% endhighlight %} +
+ +#### Step 3 - Post-upgrade steps + +##### Step 3 (A) - Database migration and cleanup + +Make sure by executing database is migrated. It should produce no errors or +output: + + foreman-rake db:migrate + foreman-rake db:seed + +You should clear the cache and the existing sessions: + + foreman-rake tmp:cache:clear + foreman-rake db:sessions:clear + +##### Optional Step 3 (B) - Reclaim database space + +After database migrations, some space can sometimes be reclaimed. It's a good idea to perform a *full* database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible. + + su - postgres -c 'vacuumdb --full --dbname=foreman' + +##### Optional Step 3 (C) - Run foreman-installer + +If you used foreman-installer to set up your existing Foreman instance we +recommend running it again after upgrading. Note that the installer can +modify config files so this may overwrite your custom changes. You can run +the installer in noop mode so you can see what would be changed. + +To see what would happen + + foreman-installer --noop --verbose + +You may see ERRORS such as `/Stage[main]/Foreman_proxy::Register/Foreman_smartproxy[foreman-hostname.domain]:` `Could not evaluate: Connection refused - connect(2)` due to httpd / apache2 service being stopped. These can be safely ignored. + +To apply these changes, run the installer again without options + + foreman-installer + +##### Step 4 - Restart + +Start the application server. This is redundant if you previously ran `foreman-installer` in step 3B. + +
+ *No operating system selected.* +
+
+{% highlight bash %} +systemctl start httpd foreman.service foreman.socket +{% endhighlight %} +
+
+{% highlight bash %} +systemctl start apache2 foreman.service foreman.socket +{% endhighlight %} +
diff --git a/_includes/manuals/3.12/3_installing_foreman.md b/_includes/manuals/3.12/3_installing_foreman.md new file mode 100644 index 0000000000..70f952de93 --- /dev/null +++ b/_includes/manuals/3.12/3_installing_foreman.md @@ -0,0 +1,3 @@ + +There are several different methods of installing Foreman. The recommended way +is with the puppet based Foreman Installer but you may also use your distribution's package manager or install directly from source. diff --git a/_includes/manuals/3.12/4.1.1_authentication.md b/_includes/manuals/3.12/4.1.1_authentication.md new file mode 100644 index 0000000000..807a5cde8e --- /dev/null +++ b/_includes/manuals/3.12/4.1.1_authentication.md @@ -0,0 +1,241 @@ + +Foreman natively supports LDAP authentication using one or multiple LDAP directories. + +#### Setting up + +Go to *Administer > LDAP Authentication*, click on *New LDAP Source* and enter the following details about the LDAP server: + +* *Name*: an arbitrary name for the directory +* *Server*: the LDAP hostname, e.g. `ldap.example.com` +* *LDAPS*: check this if you want or need to use LDAPS to access the directory +* *Port*: the LDAP port (default is 389, or 636 for LDAPS) +* *Server type*: select the implementation if listed, else choose POSIX + +Under the account tab, the details of an account used to read LDAP entries is required if anonymous binds and reads are disabled. This should be a dedicated service account with bind, read and search permissions on the user and group entries in the directory server. + +This may use the variable `$login` which will be replaced by the login of the authenticating user, however this is deprecated and will result in reduced functionality (as it only works at authentication time). + +* *Account*: leave this field empty if your LDAP server can be read anonymously, otherwise enter a user name that has read access +* *Account password*: password for the account, if defined above and when not using $login +* *Base DN*: the top level DN of your LDAP directory tree, e.g. `dc=example,dc=com` +* *Group base DN*: the top level DN of your LDAP directory tree that contains groups, e.g. `ou=Groups,dc=example,dc=com` +* *Use netgroups*: switcher that enables using netgroups instead of standard LDAP group objects, supported only for FreeIPA and POSIX LDAP server types +* *LDAP filter* (optional): a filter to restrict your LDAP queries, for instance: ```(memberOf=cn=foreman-users,ou=Groups,dc=example,dc=com)```. Multiple filters can be combined using the syntax ```(& (filter1) (filter2))```. + +#### Trusting SSL certificates + +When configuring an LDAPS connection, the certificate authority needs to be trusted. +When using Active Directory Certificate Services, ensure to export the Enterprise PKI CA Certificate using the Base-64 encoded X.509 format. + +If your LDAP server uses a certificate chain with intermediate CAs, all of the root and intermediate certificates in the chain must be trusted. + +On Red Hat based OSes: + +{% highlight bash %} +cp example.crt /etc/pki/tls/certs/ +ln -s example.crt /etc/pki/tls/certs/$(openssl x509 -noout -hash -in /etc/pki/tls/certs/example.crt).0 +{% endhighlight %} + +On Debian or Ubuntu, also ensure the file has a .crt extension: + +{% highlight bash %} +cp example.crt /usr/local/share/ca-certificates/ +update-ca-certificates +{% endhighlight %} + +#### On the fly user creation + +By checking *Automatically create accounts in Foreman*, any LDAP user will have their Foreman account automatically created the first time they log into Foreman. + +You can assign multiple organizations/locations to your LDAP authentication sources. This will assign users that are automatically created to the set of organizations/locations associated with the LDAP authentication source. Please notice this assignment happens only when users are created automatically via LDAP, and not upon every login. + +Changing the organization/location of a LDAP authentication source will not automatically change these attributes on the users in that authentication source. + +To use this feature, the relevant LDAP attributes must be specified on the next tab (e.g. firstname, lastname, email), as these will be used to populate the Foreman account. + +#### Attribute mappings + +Foreman needs to know how to map internal user account attributes to their LDAP counterparts, such as login, name, and e-mail. Examples for common directory servers are provided below. + +Note that LDAP attribute names are *case sensitive*. + +Foreman also has the ability to use a user's photo stored in LDAP as their Foreman avatar, by setting the jpegPhoto attribute mapping. + +Additional Information: + +* [Adding Display Pictures/Avatars to Red Hat IDM/FreeIPA](https://www.dalemacartney.com/2013/12/05/adding-display-picturesavatars-red-hat-idmfreeipa/) +* [Using the jpegPhoto attribute in Active Directory](https://docs.microsoft.com/en-us/archive/blogs/btrst4/using-the-jpegphoto-attribute-in-ad-part-i) + +#### Examples + +All of the examples below use a dedicated service account called 'foreman'. This should be set up with bind, read and search permissions on the user and group entries and with a strong, random password. + +##### Active Directory + +Typically either LDAPS on port 636 or LDAP on port 389. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingValue
AccountDOMAIN\foreman
Base DNCN=Users,DC=example,DC=COM
Groups base DNCN=Users,DC=example,DC=com
Login name attributeuserPrincipalName
First name attributegivenName
Surname attributesn
Email address attributemail
+
+ +Note that previously we recommended using sAMAccountName as the login name attribute. It turned out that userPrincipalName is a better choice since it does not contain white spaces that can cause issues on user creation. + +##### FreeIPA + +Typically either LDAPS on port 636 or LDAP on port 389. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingValue
Accountuid=foreman,cn=users,cn=accounts,dc=example,dc=com
Base DNcn=users,cn=accounts,dc=example,dc=com
Groups base DNcn=groups,cn=accounts,dc=example,dc=com or cn=ng,cn=compat,dc=example,dc=com if you use netgroups
Login name attributeuid
First name attributegivenName
Surname attributesn
Email address attributemail
+
+ +##### OpenLDAP + +Typically LDAP on port 389 and with anonymous queries (leave Account blank), unless configured otherwise. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingValue
Accountuid=foreman,dc=example,dc=com
Base DNdc=example,dc=com
Groups base DNdc=example,dc=com
Login name attributeuid
First name attributegivenName
Surname attributesn
Email address attributemail
+
+ +#### Linking user groups to LDAP + +A Foreman user group can be associated to a group stored in an LDAP server, so membership of the LDAP group automatically adds a user to the Foreman user group. User groups can be associated with roles, enabling users to log into Foreman and be automatically granted permissions via their membership of an LDAP group. Read more about permissions in the [Roles and Permissions](/manuals/{{page.version}}/index.html#4.1.2RolesandPermissions) section. + +To configure the association, create or edit a user group via *Administer > User groups*. The group name may be any value (no direct relation to the LDAP group). Under the *Roles* tab, select roles granting permissions to Foreman, or tick the *Admin* checkbox to enable administrator level access. + +On the *External groups* tab, click the *Add external user group* button to open a new form. In the *Name* field, enter the exact name of the LDAP group (usually the common name/CN) and select the server from the dropdown list of LDAP authentication sources. Click the *Submit* button to save changes. + +When a user logs in for the first time (assuming on the fly account creation), the ldap:refresh_usergroups cronjob runs (every 30 minutes by default) or the *Refresh* button is pressed next to the external user group entry, Foreman will synchronize the group membership from LDAP. + +##### Security Disclaimer + +Please remember your external user groups will only be refreshed automatically through the ldap:refresh_usergroups cronjob. There can be a lapse of time cronjob runs, in which if the user groups in LDAP change, the user will be assigned to the wrong external user groups. This situation can be quickly fixed by manually running ```foreman-rake ldap:refresh_usergroups``` or by refreshing the external user groups in the UI. Otherwise, the problem will eventually get fixed when the cronjob runs again. + +#### Active Directory password changes + +When using Active Directory, please be aware that users will be able to log in for up to an hour after a password change using the old password. This is a function of the AD domain controller and not Foreman. + +To change this password expiry period, see [Microsoft KB906305](https://support.microsoft.com/en-us/kb/906305) for the necessary registry change. + +#### Brute-force protection + +Foreman allows only 30 failed attempts in the last 5 minutes per one IP address by default. Any subsequent login attempts are not allowed and error message is shown: "Too many tries, please try again in a few minutes." If this is triggered by accident, the silent period can be removed by deleting failed login cache entries: + + find /usr/share/foreman/tmp/cache -name failed_login\* + +This will only work when using the file store Rails cache implementation. + +#### Troubleshooting + +If you want to use on the fly user creation, make sure that Foreman can fetch from your LDAP all the required information to create a valid user. +For example, on-the-fly user creation won't work if you don't have valid email addresses in your directory (you will get an 'Invalid username/password' error message when trying to log in). diff --git a/_includes/manuals/3.12/4.1.2_roles_and_permissions.md b/_includes/manuals/3.12/4.1.2_roles_and_permissions.md new file mode 100644 index 0000000000..e308d49650 --- /dev/null +++ b/_includes/manuals/3.12/4.1.2_roles_and_permissions.md @@ -0,0 +1,158 @@ +A user's access to the features of Foreman are constrained by the **permissions** that they are granted. These permissions are also used to restrict the set of hosts, host groups and other resources that a user is able to access and modify. + +Note: a user with global admin enabled is not restricted by the authorization system. This is the default for installations that do not have :login:true in _config/settings.yml_. + +A logged in user will be granted the **Default role** role plus one or more additional roles. The permissions and filters associated with these roles are aggregated and determine the final permission set. + +Roles may be administered by users with admin privileges or regular users with 'edit_roles' permission. In order to add new filters and permissions to a role, regular users must have the 'create_filters' permission. + +#### Roles + +These may be created, deleted and edited on the **Roles** page. Each role will contain permission filters, which define the actions allowed in a certain resource. Once your role is created, you can associate it with one or more users and user groups. + +There is one built-in system role, 'Default role'. This is a set of permissions that every user will be granted, in addition to any other roles that they have. Foreman provides you with a set of seeded roles. These roles can be assigned to users but cannot be modified in any way. They serve as a sane set of defaults and a quick starting point. If you wish to base your custom role on one of these, you can clone it and modify the clone. + +Roles can be also associated to Locations or Organizations if these are allowed. Unlike other objects this does not mean that Roles would be only available in a particular scope. Roles are always global for the entirety of Foreman. The association means that filters of such role are scoped to a particular Organization or Location. Imagine you want to create a role representing Administrator of Organization A. You can clone an existing Organization admin role and associate it with Organization A. If you later assign this role to some users, they will be granted all admin permissions but only on resources of Organization A. Note that some resources are not scopeable by Organization and Locations. Filters for such resources grant permissions globally. + +The seeded Organization admin role is similar to the Manager role. They are both being automatically extended with permissions introduced in new Foreman versions, as well as permissions introduced by plugins. The difference is that Organization admin role does not contain permissions for managing organizations, only for viewing them. Since organization administrator does not usually need to create or modify other organizations, the Organization admin role fits better this scenario. + +System admin role is a seeded role with very powerful abilities. The purpose of this role is to set up environment for others to use. It can create organizations/locations but does not have access to the resources inside them. System admin can create new users and assign them to locations/organizations and add roles to the users. System admin can view and edit settings. But most importantly, users with this role can even delegate roles that they themselves do not own. Users having this role can potentially step out of it by creating a new user with roles/permissions that they do not have as System admin and log in as the newly created user. Therefore only trusted users should be allowed to have this role. + +#### Filters + +Filters are defined within the context of a role, clicking on the 'filters and permissions' link. A filter allows a user to choose a **resource** (Hosts, Host groups, etc...) and the **permissions** that should be granted for that resource. After a filter has been created, users given a role containing this filter will have the permissions for the resource specified at the filter. + +If the filter is marked as 'Unlimited?', the permissions created in this filter will apply to all objects in the chosen resource. For instance, if the resource is Host, and the permissions are 'view' and 'index', and 'Unlimited?' is checked, users that have a role with this filter will be able to 'view' and 'index' all hosts in the system. + +When 'Unlimited?' is unchecked, a text box allowing to define more granular filtering will be enabled. You can write a search query and permissions in this filter will be applied to the results of that query only. An example of a query for the resource Host could be 'os = RedHat'. In this case, the permissions in this filter will be applied only to Hosts whose Operating System is set to Red Hat. You can test your search queries at the index page of your resource, in this case that would be '/hosts'. + +Some example queries for the resource Host: + +1. Ownership and domain membership: 'owner_id = 95 and domain = localdomain' - Will apply permissions to hosts owned by User with id 95 and in the domain 'localdomain' + + +2. Compute resource membership: 'compute_resource = Openstack' - Will apply permissions to hosts deployed on compute resource Openstack. + + +3. Fact filtering: 'facts.alarmlevel = high' - Will apply permissions to hosts with a fact 'alarmlevel' with value 'high'. As a fact is only generated during a puppet run, this filter will only refer to machines that have been built and therefore cannot be used to restrict the creation of machines. + + +These pools of queries can be combined by adding them together or the filters can be used to restrict the selected resource to a smaller and smaller subset of the total. Think of them as set operations. + +As already mentioned, a Role can be assigned to Organizations and Locations. In such case, all filters for resources that support such scoping automatically apply the same Organizations and Locations. If you want to combine filters with different Organizations or Locations assignments, you can use 'Override' check box. When checked you can override Organizations and Location for a filter. If you uncheck this field, the filter starts inheriting its role Organizations and Locations after submitting again. If you want to reset all role filters to start inheriting, you can use 'Disable all filters overriding' button on role's 'Filters' tab. + +![Disable all filters override](/static/images/screenshots/4.1.2_filters_override.png) + +We recommend managing Organizations and Locations association on Role level to keep the setup simple and clear. + +Note: If the "Administrator" check box is checked for a user, filtering will not take effect. + +#### Permissions + +These determine the operations that are allowed to be performed upon the resources to which they refer. For a few simple items like bookmarks, this operates as expected - it grants permission for all bookmarks. But for most resources, such as the hosts a user is able to operate on, there is an additional layer of security called filtering. + +When editing a filter there is a search field at the bottom that narrows the scope of the permissions granted to a subset of the resource objects. Most permission types support this search field however there are some exceptions. The permission for creating objects can't be limited by a search query because the object does not exist during creation. Therefore a user is granted the create permission if they are associated with any filter containing this permission (limited by search or not). + +Following table lists some of permissions and their impact: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PermissionDescription
Permissions for Architectures, Authentication providers, environments, External variables, Common parameters, Medias, Models, Operating systems, Partition tables, Puppet classes and User groups
viewThe user is allowed to see this type of object when listing them on the index page
createThe user is allowed to create this type of object
editThe user is allowed to edit this type of object
destroyThe user is allowed to destroy this type of object
Permissions for Domains
viewThe user is allowed to see a list of domains when viewing the index page
createThe user is allowed to create a new domain and will also be able to create domain parameters
editThe user is allowed to edit a domain and will also be able to edit a domain's parameters. If they have domain filtering active in their profile then only these domains will be editable
destroyThe user is allowed to destroy a domain and will also be able to destroy domain parameters. If they have domain filtering active in their profile then only these domains will be deletable
Permissions for Host groups
viewThe user is allowed to see a list of host groups when viewing the index page
createThe user is allowed to create a new host group and will also be able to create host group parameters
editThe user is allowed to edit a host group and will also be able to edit a host group's parameters. If they have host group filtering active in their profile then only these host groups will be editable
destroyThe user is allowed to destroy a host group and will also be able to destroy host group parameters. If they have host group filtering active in their profile then only these host groups will be deletable
Permissions for Hosts
viewThe user is allowed to see a list of hosts when viewing the index page. This list may be constrained by the user's host filters
createThe user is allowed to create a new host. This operation may be constrained by the user's host filters
editThe user is allowed to edit a host. This operation may be constrained by the user's host filters
destroyThe user is allowed to destroy a host. This operation may be constrained by the user's host filters
Permissions for Users
viewThe user is allowed to see a list of users when viewing the index page. A user will always be able to see their own account even if they do not have this permission
createThe user is allowed to create a new user
editThe user is allowed to edit existing users. A user will always be able to edit their own basic account settings and password
destroyThe user is allowed to delete users from the system
diff --git a/_includes/manuals/3.12/4.1.3_trends.md b/_includes/manuals/3.12/4.1.3_trends.md new file mode 100644 index 0000000000..b573db12d3 --- /dev/null +++ b/_includes/manuals/3.12/4.1.3_trends.md @@ -0,0 +1,5 @@ + +Trends and statistics are moved to the separate plugin. +See [manual](/plugins/foreman_statistics) for the reference. + +There is a rake task `foreman-rake purge:trends` for users who are not planning to use trends and statistics anymore and wish to clean up database. diff --git a/_includes/manuals/3.12/4.1.4_auditing.md b/_includes/manuals/3.12/4.1.4_auditing.md new file mode 100644 index 0000000000..79c28675b2 --- /dev/null +++ b/_includes/manuals/3.12/4.1.4_auditing.md @@ -0,0 +1,57 @@ + +Foreman supports auditing of almost all changes that happen within Foreman, from both the UI and from the API. Auditing is done at a user level, and is thus ineffective if _:login:_ is set to _false_, as all audits will be done as the 'admin' user. + + +#### Basic View + + +Go to the Audit tab to see a view of what has changed. This view can be +filtered by the type of change or by the object that was altered (e.g. search +for a hostname to see all changes relating to that host). You also get the +parent object - so if a parameter was modified, you can see what host/group that parameter belongs to. The timestamp of the change and the user who performed it will be listed. + + +#### Extended Audits for Templates + + +Template changes also store a diff of the changes, and the ability to roll back to a previous version of the template. + +#### Expire old audits automatically + +You will probably want to delete your old audits after some time. To achieve this, there is a cronjob. This job invokes +rake task `audits:expire`. There is no default value for number of days to keep because every user has different needs. +However, you can configure an amount of days to keep in Foreman in Settings (`Administer -> Settings -> General (Tab) -> Save audits interval`) to fit to your needs. You can leave value empty to no expire old audits. Also this task can be invoked manually whenever required. Invocation can be done by `foreman rake audits:expire`. If the `days` parameter is not provided, the task is trying to take configured value from `Settings`. If this value is also empty, task is closed and no audits are expired. + +Available parameters: +* days => number of days to keep audits (defaults to 90) + +Examples: +1. Expires all audits older then 7 days + +``` +foreman-rake audits:expire days=7 +``` + + +#### Anonymize old audits + +Here, anonymization clears links to user accounts and their IP addresses, but keeps all other audit data in database. + +You can anonymize your old audits instead of deleting the audit entries. +Use task `foreman-rake audits:anonymize` for this similarly to `audits:expire`. + +Example: + +1. Anonymizes all audits older then 7 days + +``` +foreman-rake audits:anonymize days=7 +``` + +#### Organizations and Locations + +Audits inherit organizations and locations of resources for which they have been created. Imagine you have a subnet assigned to organization A. Whenever you modify this subnet, the audit will be visible only in organization A. When you later add this subnet to organization B, new audits will appear in both organizations A and B. All audits created previously remain untouched. Resources that can't be assigned to any organization or location will be always visible in all organizations and locations, meaning the change has affected all organizations and locations. + +#### Audit history + +Audited resources can change in time, e.g. they have new attributes. Also audit definitions changes, e.g. new association starts to be tracked in new version of Foreman. All these changes only apply to newly created audits, old audits can't be updated and will always contain only data known back in time they were created. Starting with Foreman 1.20, audits are scoped to organizations and locations. All audits created before are unassigned, meaning only admin can see them. diff --git a/_includes/manuals/3.12/4.1.5_searching.md b/_includes/manuals/3.12/4.1.5_searching.md new file mode 100644 index 0000000000..a8895e9242 --- /dev/null +++ b/_includes/manuals/3.12/4.1.5_searching.md @@ -0,0 +1,76 @@ + +Each page in Foreman has its own search functionality, which is centred around the resources that it manages, allowing searching based on attributes of the resources in the list or resources that they're associated to. The search box also features powerful auto-completion to help build up search queries and free text search on many pages. The search functionality can also be used in the API when listing resources, see [Customize JSON Responses](/manuals/{{page.version}}/index.html#5.1.4CustomizeJSONResponses) for details. + +#### General usage + +Searching is through "field = value" or free text queries, which can be combined with logical operators (and, or, not) and parentheses to handle more complex logic. To give some examples: + +* `name = client.example.com` on the host list would show the host(s) whose hostname is client.example.com +* `hostgroup = "Web servers" and domain != lon.example.com` would show hosts in the Web servers host group, but not in the lon.example.com domain +* `Web servers` would show all hosts with that text anywhere, e.g. as their host group name or in the comment field + +The fields available depend on the type of resource that's being searched, and the names of the attributes vary depending on the context. The "name" field on the host groups list is equivalent to the "hostgroup" field on the hosts list. Requests to add additional searchable fields are welcome, and may be filed in the "Search" category [in the bug tracker](/contribute.html#Bugreporting). + +The search engine is provided by the scoped_search library, which maps search queries directly to SQL queries. The [Query Language](https://github.com/wvanbergen/scoped_search/wiki/Query-language) documentation provides A more complete specification of the syntax available. + +#### Bookmarks + +Foreman supports the ability to make search bookmarks, allows users to quickly jump to predefined search conditions. Available bookmarks can be selected from the dropdown menu to the right of the search box, or managed from *Administer > Bookmarks*. + +Some of the bookmarks are provided by default, e.g. to search for active or inactive hosts, or to only view reports with events. + +To save a query, Use the dropdown menu to the right of the search box and click "Bookmark this search". When saving, the bookmark can be labeled as public, so all other users are able to see and use it too. + +#### Free text search + +If you ignore the auto-completer and just enter text in the search field, Foreman will try searching for that text across multiple fields. + +For example, if you just enter `12` in the hosts search box, the results will include all hosts with 12 in their IP address, MAC address or name. In general the fields used for free text search are kept to a minimum for performance and accuracy reasons. It's preferable to search using a specific field, e.g. when searching for an IP address, use `ip ~ 12` instead of `12`. + +#### Searching for present/empty values + +The "has" operator matches values that are present, e.g. to search for hosts that are on a compute resource, use `has compute_resource`. + +Similarly, this can be negated, so to search for hosts without host groups, you can use `not has hostgroup`. + +#### Case sensitivity + +When querying using `=` and `!=` operators then exact, case sensitive matches will be returned. When running `~` (like) and `!~` (unlike) operators, the matching is case insensitive. + +#### Quoting + +In search queries, white spaces are used as a delimiter. Here are some examples of the way a query will be interpreted: + +* `description ~ "created successfully"`: list all notifications that contain "created successfully" +* `description ~ created successfully`: list all notifications that contain "created" and at least one of its text fields contains "successfully" +* `description !~ created successfully`: list all notifications that doesn't contain "created" and at least one of its text fields contains "successfully" + +In the second and third example, "successfully" is an additional term that is interpreted as a free text search + +#### Wildcards ('_', '%', '*') + +The `~` and `!~` search operators are translated to the `LIKE` and `NOT LIKE` SQL queries respectively, which support two basic wildcards, `_` and `%`. + +`_` is a wildcard for a single character replacement. For example, the search `name ~ fo_` will match both "foo" and "for". + +The `%` and `*` wildcard will replace zero or more characters. For example, the search `name ~ corp%` will match both "corp" and "corporation". The more common ‘*’ wildcard is not a SQL wildcard but may be used instead. + +When the `~` or `!~` search is processed, a ‘%’ wildcard is automatically added at the beginning and end of the value if no wildcard is used, so it will by default match at any location inside a string. For example, the search `name ~ foo` is equivalent to `name ~ %foo%` and the search `name ~ foo%` will only match "foo" at the beginning of the value. + +#### Date-time search query syntax + +Many date and time formats are accepted in search queries. Here are some examples: + +* "30 minutes ago", "1 hour ago", "2 hours ago", Today, Yesterday +* "3 weeks ago", "1 month ago", "6 days ago", "July 10,2011" + +The date can have different separators, "10-July-2011" will be interpreted in the same way as "10/July/2010" or "10 July 2011" Month names may be the full English name or a three letter abbreviation, e.g. "Jan" will be interpreted as "January". Many other formats are also acceptable, however it is not recommended to use ambiguous formats such as "3/4/2011" + +The valid date time operators are ‘=’, ‘<’ and ‘>’ which are interpreted as ‘at’, ‘before’ and ‘after’ respectively. This is how the search term interpeted: + +The right hand part of a date-time condition is parsed and translated into a specific date-time, "30 minutes ago" is translated to "now - 30 minutes". + +* `last_report > "2011-07-01 12:57:18 EDT"` should be read as created after this time +* In the same way, `last_report > "30 minutes ago"` should be read as "created after 30 minutes ago" and not "created more then 30 minutes ago" + +A search query like `installed_at = Yesterday` is translated into a period query, it will be translated at runtime to match a range of date-times. For example, if running on Jan 1, it would be translated into "(installed_at >= Jan 1,2012 00:00) and (installed_at < Dec 31,2011 00:00)". diff --git a/_includes/manuals/3.12/4.1.6_user_management.md b/_includes/manuals/3.12/4.1.6_user_management.md new file mode 100644 index 0000000000..d4fc28d908 --- /dev/null +++ b/_includes/manuals/3.12/4.1.6_user_management.md @@ -0,0 +1,7 @@ + +Foreman is all about hosts and users interacting with these hosts. + +#### SSH Keys + +Each Foreman user can have multiple SSH keys assigned when editing a user. These keys alone do not serve any purpose, but are available for use in provisioning templates and can be accessed via ENC data. They provide an easy way to manage users and login ssh keys on hosts without the need for LDAP. +If you want users to be able to login to a host using the data provided in Foreman, you need to include the `create_users` snippet in your provisioning template. There is a [puppet module](https://github.com/ekohl/puppet-foreman_simple_user) available to keep user data in sync with Foreman and your hosts. diff --git a/_includes/manuals/3.12/4.10.1_global_status.md b/_includes/manuals/3.12/4.10.1_global_status.md new file mode 100644 index 0000000000..ec9f894023 --- /dev/null +++ b/_includes/manuals/3.12/4.10.1_global_status.md @@ -0,0 +1,23 @@ +The global status represents the overall status of a particular host. The +status can have one of three possible values - **OK**, **Warning** or +**Error**. + +OK means that no errors were reported by any sub-status. It is represented +with the color green. + +Warning suggests that user should verify the status, while +no error was detected, some sub-status raised a warning. A good example would +be that there are no Puppet reports for the host even though the host is +configured to send Puppet reports. Therefore it is highlighted with the color +yellow. + +The last possible value is Error which indicates that some sub-status +reports a failure. This could for example mean that Puppet run contains +some failed resources. Obviously it is something that should be fixed and +is user is alerted by the color red. + +You can find global status on hosts overview page displayed as a small icon +next to host name with corresponding color. Hovering over the icon renders +a tooltip with sub-status information to quickly find out more details. + +![Global statuses](/static/images/screenshots/4.9.1_global_statuses.png) diff --git a/_includes/manuals/3.12/4.10.2_substatuses.md b/_includes/manuals/3.12/4.10.2_substatuses.md new file mode 100644 index 0000000000..17d5ac6db8 --- /dev/null +++ b/_includes/manuals/3.12/4.10.2_substatuses.md @@ -0,0 +1,60 @@ +A sub-status monitors only a part of host capabilities. Currently Foreman ships +only two - **build** and **configuration** sub-statuses. Not all sub-statuses +are relevant for all hosts, therefore configuration is only considered if host +is using some configuration management system, e.g. has some Puppet proxy +associated. Build sub-status is relevant for managed hosts and when Foreman is +run in unattended mode. + +You can see a global host status with all sub-statuses on the host detail page, +in the properties table. Note that there can be more sub-statuses added by +plugins. + +![All statuses](/static/images/screenshots/4.9.2_all_statuses.png) + +Each sub-status can define own set of possible values that are mapped to three +global status values. Build sub-status has two possible values - **pending** +and **built** that are both mapped to global OK value. Configuration status +is more complicated and its possible values and mappings are described in table +below. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status valueMaps toDescription
ErrorErrorError during configuration, e.g. Puppet run failed to install some package
Out of syncWarningA configuration report was not received within the expected interval, based on the outofsync_interval1
No reportsWarning / OKWhen there are no reports but the host uses configuration management system (e.g. Puppet proxy is associated) or always_show_configuration_status setting is set to true, it maps to Warning. Otherwise it is mapped to OK.
ActiveOKDuring last Puppet run, some resources were applied
PendingOKDuring last Puppet run, some resources would be applied but Puppet was configured to run in noop mode
No changesOKDuring last Puppet run, nothing has changed
+ +1 Reports are identified by an origin and can have different intervals based upon it. For example, reports by Puppet will have 'Puppet' as it's origin and will have it's interval set by puppet_interval. diff --git a/_includes/manuals/3.12/4.10.3_searching_by_statuses.md b/_includes/manuals/3.12/4.10.3_searching_by_statuses.md new file mode 100644 index 0000000000..09806e9277 --- /dev/null +++ b/_includes/manuals/3.12/4.10.3_searching_by_statuses.md @@ -0,0 +1,24 @@ +You can search hosts by global status. Some examples can be found below: + +* search for all hosts that are OK + + `global_status = ok` + +* search for all hosts that deserves some attention + + `global_status = error or global_status = warning` + +To search hosts based on configuration status you can search by last report +metrics like this: + +* find hosts that have at least one pending resource + + `status.pending > 0` + +* find hosts that restarted some service during last puppet run + + `status.restarted > 0` + +* find hosts that have an interesting last Puppet run (something happened) + + `status.interesting = true` diff --git a/_includes/manuals/3.12/4.10_monitoring.md b/_includes/manuals/3.12/4.10_monitoring.md new file mode 100644 index 0000000000..f3b45ea89f --- /dev/null +++ b/_includes/manuals/3.12/4.10_monitoring.md @@ -0,0 +1,5 @@ +To monitor your infrastructure, host statuses are useful. In Foreman each host +has a *global* status that indicates which hosts need attention. Each host also +has sub-statuses that represents status of a particular feature. With any change +of a sub-status, the global status is recalculated and the result is determined +by statuses of all sub-statuses. diff --git a/_includes/manuals/3.12/4.11.1_report_templates.md b/_includes/manuals/3.12/4.11.1_report_templates.md new file mode 100644 index 0000000000..49e46f8786 --- /dev/null +++ b/_includes/manuals/3.12/4.11.1_report_templates.md @@ -0,0 +1,27 @@ +You can find existing report templates under *Monitor -> Report Templates*. Foreman +comes with few default report templates that are locked. As with other templates, +we do not recommend unlocking and modifying them, as they are automatically updated +on upgrades. If a change of default template is desired, it's recommended to clone +the template and do adjustments in the clone. + +#### Generating + +To generate a report out of the report template, find the report template and click +the *Generate* button. This will evaluate a template and respond with text file +for download. The rendering itself is done in a background process, but it can run +for a long time. + +There's a separate permission for generating the report, so only selected users +can perform resource heavy operations while another users can prepare the report +templates. + +##### Scheduling and delivering reports via e-mail + +In the form for report generating you can choose a starting time for delayed rendering. +There is no way to schedule repetitions, but as the report generating can be started +by a *hammer report-template* command, scheduling can be achieved using cron. +For these planned reports, as well as for long running reports, it is no longer useful +to have the report downloaded by the web browser. In such cases you can choose to get +the report delivered via e-mail by simply checking *Send report via e-mail* and +filling the e-mail addresses field. Your default e-mail address is prefilled, +but you can fill other(s) and send reports for further processing. diff --git a/_includes/manuals/3.12/4.11.2_macros.md b/_includes/manuals/3.12/4.11.2_macros.md new file mode 100644 index 0000000000..bf69522d77 --- /dev/null +++ b/_includes/manuals/3.12/4.11.2_macros.md @@ -0,0 +1,26 @@ +For report templates, it's useful to access more data from database than in regular +provisioning templates. Typically it's needed to load all hosts matching some search +query. If safe mode rendering is enabled, access to internal objects is restricted. +Foreman provides resource loading macros such as load_hosts. They all have following +behaviors and capabilities: + +* accepts search keyword to limit what resources should be loaded +* accepts include keyword to specify associated objects that should be eager loaded +* load data in batches +* authorize the resources based on current user permissions + +Consider following example: + +```erb +<%- load_hosts(search: 'name ~ example.com').each_record do |host| -%> +<%= host.name %>,<%= host.mac %> +<%- end -%> +``` + +It loads all hosts that contains domain example.com in their name. If it's more than +1,000 hosts, it will trigger separate SQL query for each thousand automatically. Then +it iterates over all found hosts and print comma separated pair of host name and MAC +address. The query will return only hosts that current user has view_hosts permission +for. + +For more examples see default report templates. diff --git a/_includes/manuals/3.12/4.11_reports.md b/_includes/manuals/3.12/4.11_reports.md new file mode 100644 index 0000000000..4d78e2d8d1 --- /dev/null +++ b/_includes/manuals/3.12/4.11_reports.md @@ -0,0 +1,6 @@ +Foreman provides reporting capabilities. It uses the same templating engine +as for provisioning templates and partition tables. The list of macros that +can be used in this context slightly differs as reports are usually rendered +for a specific host. Reports do not enforce any output format as the formatting +is part of the template itself, the only requirement is, that the resulting +output is textual form. diff --git a/_includes/manuals/3.12/4.2.1_puppet_envs.md b/_includes/manuals/3.12/4.2.1_puppet_envs.md new file mode 100644 index 0000000000..38c02b094c --- /dev/null +++ b/_includes/manuals/3.12/4.2.1_puppet_envs.md @@ -0,0 +1,30 @@ + +Puppet environments are mapped directly into Foreman. They can be used at various levels throughout the Foreman interface. Puppet environments are generally used to separate classes from different types of Host, typically allowing changes to a module to tested in one environment (e.g. development) before being pushed to another (e.g production). + +#### Defining environments + +There are several ways to create Puppet environments within Foreman. + +##### Importing from Puppet + +Foreman can detect all the environments and classes contained on a Puppet server, and import them automatically. To do this, go to *Configure > Environments* and click on *Import from <proxy-name>*. Foreman will scan the Puppet server via the Smart Proxy, and display a confirmation of the detected changes. Select the changes you wish to apply and confirm. + +More information about configuring the Smart Proxy to read environments and Puppet classes is in the [Smart Proxy Puppet](/manuals/{{page.version}}/index.html#4.3.6Puppet) section. + +Note that the Smart Proxy will only detect environments that contain one or more Puppet classes, so ensure that at least one Puppet module containing a class has been deployed to the Puppet server. + +##### Manual creation + +To create an environment by hand, simply go to *Configure > Environments* and click *New Puppet Environment*. Give the new environment a name and save. Note that if the environment doesn't exist on the Puppet server and you subsequently run an import (above), Foreman will prompt for the environment to be deleted. + +#### Assigning environments to hosts + +This is done from the Host Edit page, on the Host tab. Selecting an environment will filter the classes visible on the Puppet Classes tab to just the classes in the selected environment. + +You can also also mass-assign an environment to a group of hosts - tick the checkboxes of the required hosts in the Hosts list, and then select *Change Environment* from the *Select Action* dropdown menu at the top of the page. + +#### Environments with host groups + +You can assign an environment to a hostgroup as well. This functions as a form +of default - a user creating a new host and selecting the hostgroup will +automatically have the environment pre-selected. The user is not prevented from changing the environment of the new host, it simply saves a few clicks if they are happy with it. diff --git a/_includes/manuals/3.12/4.2.2_puppet_classes.md b/_includes/manuals/3.12/4.2.2_puppet_classes.md new file mode 100644 index 0000000000..475ea2ad6d --- /dev/null +++ b/_includes/manuals/3.12/4.2.2_puppet_classes.md @@ -0,0 +1,130 @@ + +Puppet classes are generally imported from the Puppet server(s) via the Import +button on the Puppet Classes page. They can also be created by hand, and +manually associated with a set of environments (for filtering purposes). + +#### Importing Classes + +Go to *Configure > Classes* and click the Import button. This will not be visible unless you have at least one Puppet server with a puppet-enabled Smart Proxy. Only classes from modules will be imported, and the Puppet manifests *must* be valid in order for the Smart Proxy to parse them. Use `puppet parser validate` to test the syntax of Puppet manifests. + +More information about configuring the Smart Proxy to read environments and Puppet classes is in the [Smart Proxy Puppet](/manuals/{{page.version}}/index.html#4.3.7Puppet) section. + +##### The "Hosts" Column + +Under *Configure > Classes* you will also see a column called "Hosts". This column represents the number of hosts the given module/class has been assigned to. Clicking this figure will list the hosts. + +##### Ignoring classes on import + +It's often to have a module structure like this: + + +{% highlight sh %} +$ tree git/ +git/ +└── manifests + ├── init.pp + ├── install.pp + ├── params.pp + └── repo.pp +{% endhighlight %} + +In this situation, Foreman would offer to create: + +{% highlight sh %} +git +git::install +git::params +git::repo +{% endhighlight %} + +However, if we know that the subclasses are not intended for direct consumption, but are only really part of the internal structure of the module, then we would want to exclude those from the import mechanism, so that Foreman only offers to import *git*. We can achieve this via the file */usr/share/foreman/config/ignored_environments.yml*. + +This file is read during each import, causing Foreman to ignore changes to the listed environments or Puppet classes that match the expressions in the file. It will not delete any environments or classes already in Foreman. + +Entire environments can be ignored with this configuration: + +{% highlight yaml %} +:ignored: + - development + - testenv +{% endhighlight %} + +Classes can be ignored using a set of regular expressions - any class which matches one of them will not be imported. So, for the above example, we might configure: + +{% highlight yaml %} +:filters: + - !ruby/regexp '/install$/' + - !ruby/regexp '/params$/' + - !ruby/regexp '/repo$/' +{% endhighlight %} + +Regular expression features such as negative lookaheads can be used for more advanced filtering, e.g. to ignore all classes except for those starting with "role::", the following syntax can be used: + +{% highlight yaml %} +:filters: + - !ruby/regexp '/^(?!role::)/' +{% endhighlight %} + +#### Assigning classes to hosts + +To cause Puppet to apply your classes, you will need to assign them to your +hosts. This can be achieved in a number of ways - the best method may vary +depending on how many classes you intend to assign and whether any parameters +need to be overridden. + +##### Individual host assignment + +When editing a host, Puppet classes may be assigned directly under the *Puppet +Classes* tab. All classes that are in the Puppet environment selected on the +first *Host* tab will be listed. + +##### Via a host group + +Host groups tend to correspond to an infrastructure role as each host may be +assigned to a single host group, and typically inherits most of its Puppet +classes in this way. + +Puppet classes can be assigned by editing the host group and selecting them +on the *Puppet Classes* tab. + +Most host group attributes are copied to a host when it is created, however +Puppet class associations remain inherited from the host group throughout its +lifetime. Any change to a host group's assigned Puppet classes or parameters +will affect any host with that host group set. + +The Puppet environment attribute may be different on the host to the host +group, which means that Puppet classes assigned to the host group may not +exist in the host's own Puppet environment. Any Puppet classes that are +inherited from the host group, but do not exist in the host's environment will +be left out when Foreman renders the ENC (YAML) output. Check under +*Configure > Puppet classes* that the classes are available in both the host +group and host environments if they differ. + +You can also also mass-assign a host group to a number of hosts - tick the +checkboxes of the required hosts in the Hosts list, and then select *Change +Group* from the *Select Action* dropdown menu at the top of the page. + +##### Using config groups + +A config group provides a one-step method of associating many Puppet classes +to either a host or host group. Typically this would be used to add a +particular application profile or stack in one step. + +To create a config group, click on *Configure > Config groups*, click *New +Config Group*, enter a name and select the desired Puppet classes. When +editing either a host or host group, the new config group can be added at the +top of the *Puppet Classes* tab. + +Config groups are not specific to an environment and so only those Puppet +classes that are in the host's environment when rendering the ENC (YAML) will +be listed. Any classes that are not listed in the environment (as per +*Configure > Classes*) will be left out. + +Note that it isn't possible to use a smart class parameter override with a +config group, as a host may have many config groups with no way to define an +order of precedence. Overrides should be made on a host group, host or other +attribute. + +##### Checking the results + +To see how Foreman is passing the classes to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the Puppet server - the classes will be in the "classes" hash. diff --git a/_includes/manuals/3.12/4.2.3_puppet_params.md b/_includes/manuals/3.12/4.2.3_puppet_params.md new file mode 100644 index 0000000000..7762ee09d5 --- /dev/null +++ b/_includes/manuals/3.12/4.2.3_puppet_params.md @@ -0,0 +1,61 @@ +Foreman can pass two types of parameters to Puppet via the ENC ([External Node Classifier](https://docs.puppetlabs.com/guides/external_nodes.html)) interface - global parameters (accessible from any manifest), and class parameters (scoped to a single Puppet class). These can be added in a number of ways through Foreman. + +Generally speaking, it's best to use class parameters where possible, as this makes designing, using and sharing Puppet modules and classes easier. The class may clearly specify which parameters it expects, provide sensible defaults and allow users to override them. Foreman is also able to import information about class parameters automatically, making it easier to consume new classes without needing to know and enter the precise names of global parameters. + +#### Types of parameters in Puppet + +In Puppet's DSL, accessing a global parameter or variable is done using `$::example` (preferred) or `$example` for a parameter named "example" in Foreman. More information about accessing variables is available in the [Puppet Language: Variables](https://docs.puppetlabs.com/puppet/latest/reference/lang_variables.html#syntax) documentation. When looking at the ENC (YAML) output from Foreman, a global parameter will look like this: + +{% highlight yaml %} +parameters: + example: "foo bar" +{% endhighlight %} + +When using class parameters, a [class will first be defined](https://docs.puppetlabs.com/puppet/latest/reference/lang_classes.html#defining-classes) with a parameter and may be accessed either using the local name or fully-qualified, e.g. + +{% highlight ruby %} +class example($setting) { + notice($setting) + notice($::example::setting) # fully-qualified +} +{% endhighlight %} + +When looking at the ENC (YAML) output from Foreman, a class and class parameter will look like this: + +{% highlight yaml %} +classes: + example: + setting: "foo bar" +{% endhighlight %} + +#### Types of parameters in Foreman + +Global parameters in Foreman can be added in the following places: + +* Globally, per-resource (e.g. host group, domain) or per-host +* [Smart variables](/manuals/{{page.version}}/index.html#4.2.4SmartVariables) + +Class parameters in Foreman can be set in: + +* [Puppet classes, as a smart class parameter](/manuals/{{page.version}}/index.html#4.2.5ParameterizedClasses) + +#### Global parameters + +Host inherit their list of global parameters from the following locations, in order of increasing precedence: + +* Globally defined parameters, under *Configure > Global parameters*. These apply to every host. +* Organization-level parameters, under *Administer > Organizations > edit > Parameters*. +* Location-level parameters, under *Administer > Locations > edit > Parameters*. +* Domain-level parameters, under *Infrastructure > Domains > edit > Parameters*. +* Subnet-level parameters, under *Infrastructure > Subnets > edit > Parameters*. +* Operating system-level parameters, under *Hosts > Operating systems > edit > Parameters*. +* Host group-level parameters, under *Configure > Host groups > edit > Parameters*. +* Host parameters, under *Hosts > All hosts > edit > Parameters*. + +The final (most specific) level of global parameters applies only to a single host. Edit a Host and switch to the *Parameters* tab, and you will see all of its inherited parameters from the previous levels. You can override any of these previously-defined parameters or define new ones here. + +Global parameters support multiple data types and validation as per type selected. With types support, searching by parameter value is no longer allowed. + +#### Checking the results + +To see how Foreman is passing the parameters to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the Puppet server - the parameters will be in the "parameters" hash. diff --git a/_includes/manuals/3.12/4.2.4_param_classes.md b/_includes/manuals/3.12/4.2.4_param_classes.md new file mode 100644 index 0000000000..2632627ad3 --- /dev/null +++ b/_includes/manuals/3.12/4.2.4_param_classes.md @@ -0,0 +1,94 @@ + +Parameterized class support permits detecting, importing, and supplying parameters direct to classes which support it, via the ENC. This requires Puppet 2.6.5 or higher. + +#### Setup + +By default, parameterized class support is enabled in Foreman. This can be checked from *Administer > Settings > Puppet* and ensure *Parametrized_Classes_in_ENC* is set to *true*. + +![Settings](/static/images/screenshots/param_classes/settings.png) + +Now you'll need to import some parameterized classes from your Puppet server. +If you don't have any parameterized classes in your modules dir, the +foreman-installer has several, you can download a few modules from the Puppet +Forge. Once you have some parameterized modules, import your classes (see +[**4.2.2 Classes**](manuals/{{page.version}}/index.html#4.2.2Classes)) + +![Import](/static/images/screenshots/param_classes/1.17/import.png) + +#### Configure a class + +This example will work with the *foreman* class from the installer. Click on the class, and you should get a page with 3 tabs, like so: + +![3 Tabs](/static/images/screenshots/param_classes/3tabs.png) + +The middle tab, "Smart Class Parameter", is the important one. Click onto that, and you should see something like this: + +![Edit](/static/images/screenshots/param_classes/1.14/edit.png) + +On the left, we have a list of possible parameters that the class supports. On the right, we have the configuration options for the parameter selected. + +Lets configure the *foreman* class to change the user the foreman processes run as. Select the *user* parameter, at the end of the list. Now lets go through the options: + +* Key + * This can't be edited, it's just for information +* Description + * Purely informational textbox for making notes in. Not passed to Puppet, or reused anywhere else +* Puppet Environments + * This can't be edited, it's just for information +* Override (**important**) + * If this is unchecked, Foreman will not attempt to control this variable, and it will not be passed to Puppet via the ENC. +* Key type + * The type of data we want to pass. Most commonly a string, but many other data types are supported. There's no easy way to tell what type of data Puppet is expecting, so you will need to read through the code/documentation that comes with a particular module to find out. Changing the type field requires an appropriately set "Default Value" field. +* Default Value + * This will be imported from Puppet initially, but if Puppet is using any class inheritance, you'll get something unhelpful like "${$foreman::params::user}". This is because Foreman won't follow the inheritance, so you'll need to set a sensible default value +* Omit + * Should the parameter be omitted from the ENC provided to puppet by default. This is useful if you want to use the puppet default in most cases, but want to override the value just in certain cases specified by the matchers. +* Hidden value + * Should the values of the smart class parameter be hidden in the UI. + +Ok, so let's configure our *user* parameter. We want to tick Override, set type to "String" and set the default value to "foreman", like so: + +![User Param](/static/images/screenshots/param_classes/1.14/user_param.png) + +
Tip: you can set Override on all parameters on a class from the Puppet classes list, clicking the dropdown menu on the right and clicking "Override all parameters".
+ +#### Default value + +Most importantly, the *Override* option has to be enabled for Foreman to control this variable, otherwise it will never be managed and will not appear in the ENC output. + +The *Default value* will be supplied in the ENC output and should be a supported value, such as a string, YAML or JSON structure or use template features (see following sections). When the *Omit* checkbox is enabled, no default value will be present in the ENC output unless an override matches. Puppet will instead use the class default or data binding (Hiera) as usual. + +The default will be imported from the Puppet manifest initially, but if the class uses an inherited params pattern, it may contain an unhelpful string such as `${$foreman::params::user}`. Foreman is unable to parse the actual value in this case as it might change when evaluated. Change the suggested default to the actual value, or tick the *Omit* checkbox. + +![Omit](/static/images/screenshots/param_classes/1.14/omit.png) + +#### Setting up matchers + +We've configured the default, but that's not very useful. We need to be able to override the default for hosts or groups of hosts. To do that we need the "Override Value For Specific Hosts" section at the bottom of the page. + +Let's say that any machine in the "development" Puppet environment should use a value of "foremandev" instead of "foreman" for the "user" parameter. Add "environment" to the end of the matchers list, then click the "New Matcher-Value" button, and fill it out like this: + +![Matcher](/static/images/screenshots/param_classes/1.14/matcher.png) + +This is a basic configuration - for more complex examples of using matchers, +see the [Smart Matchers](manuals/{{page.version}}/index.html#4.2.6SmartMatchers) section. + +#### Overriding a parameter for a host + +If Foreman manages the value of a class parameter ("override = true"), it's also possible to update a host-specific override from the host itself. That way you don't have to grant access to the Puppet Classes page to everyone. From a Host, click Edit, go to the Parameters tab, and you'll see the variable, the class-scope, and the current value. You can then override the value for that host: + +![Host Edit](/static/images/screenshots/param_classes/1.14/hostedit.png) + +If the value is hidden you can click the unhide button to temporarily see the value while you edit. Clicking the button won't change the hidden property for the parameter, only show it for editing purpose. + +![Hide button](/static/images/screenshots/param_classes/1.14/hide_button.png) + +If you go back and look at the Puppet class, you'll see Foreman has added a matcher for that host: + +![Host Matcher](/static/images/screenshots/param_classes/1.10/hostmatch.png) + +The same override button is available on a host group's *Parameters* tab. For more complex logic, like matching on facts, use the Puppet Class page. + +#### Advanced usage + +Smart class parameters are based on the smart matchers technology, and have a number of advanced features such as validation and multiple data types. More about these can be found in the [Smart Matchers](manuals/{{page.version}}/index.html#4.2.6SmartMatchers) section. diff --git a/_includes/manuals/3.12/4.2.5_matchers.md b/_includes/manuals/3.12/4.2.5_matchers.md new file mode 100644 index 0000000000..3d5f18685c --- /dev/null +++ b/_includes/manuals/3.12/4.2.5_matchers.md @@ -0,0 +1,270 @@ + +The smart matching technology underpins smart class parameters, so is described below. It provides the following features for each parameter: + +1. A default value that can be sent if no specific match is found. +1. An order of precedence for overrides, based on host attributes or facts. +1. A list of overrides (matchers). +1. Specifying a data type, allowing strings, integers and data structures to be passed natively to Puppet. +1. Optional validation of values. +1. Template processing of values for dynamic content. + +#### Ordering + +Overrides are processed in the order of precedence set in the *Order* field, from most to least specific (first match wins, unless merging is enabled). This is a list of host attributes and fact names that overrides will be checked against. If no override from this list matches, the default value is used. + +Example attributes that may be listed are: + +* `fqdn` - host's FQDN ("host.example.com") +* `hostgroup` - full name of the host group, including parents ("Europe/Web servers"). Matchers on host groups can be inherited by their children, see documentation for `matchers_inheritance` in [configuration options.](manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) +* `os` - name and version of operating system ("RedHat 6.4") +* `domain` - host's domain name ("example.com") +* `location` or `organization` - full name of the location/organization, including parents ("Company/Subsidiary"). Matchers on location/organization can be inherited by their children, see documentation for `matchers_inheritance` in [configuration options.](manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) +* `is_virtual` - a fact [supplied by Facter](https://docs.puppetlabs.com/facter/latest/core_facts.html#isvirtual) + +The default order is set under *Administer > Settings > Puppet > Default_variables_Lookup_Path* and is "fqdn", "hostgroup", "os", "domain". + +Note that there's a name conflict between the "operatingsystem" fact and Foreman's attribute "operatingsystem" (same as "os" above), and Foreman's attribute will be the one that is used, so will include the version number. + +#### Overrides / matchers + +Once defaults have been filled in for your parameter, you can then add criteria to match against - click the *Add Matcher* button under your parameter, and more input fields will appear: + + + + + + + + + + + + + + + +
Attribute typeShould state a name = value relationship that Foreman use to match against the entries in the order list
ValueWhat the parameter should be in the ENC, if this rule is matched
OmitInstead of providing a value, this parameter will not be supplied in the ENC output (use to prevent a default value being returned) - only for smart class parameters
+ +As an example, let's say that any machine in the "development" puppet environment should use a value of "foremandev" instead of "foreman" for the "user" parameter. Add "environment" to the end of the matchers list, then click the *Add Matcher-Value* button, and fill it out like this: + +![Matcher](/static/images/screenshots/param_classes/1.14/matcher.png) + +The match field currently supports string equality only, the values must match exactly. + +##### Merging overrides + +When the data type is a hash or array, ticking *Merge overrides* will cause values from every override that matches (e.g. an FQDN *and* domain) to be merged together. + +Merging is "deep", so nested hashes and arrays will gain values rather than being overwritten entirely. + +The *Merge default* option adds the default value as one of the values to merge, it will get the least important priority so one of the other values may overwrite it. + +When the data type is an array, the *Avoid duplicates* option will de-duplicate the resulting array. + +#### Data types + +The type of data we want to pass to Puppet can be set in the *Parameter type* field. Most commonly a string, but many other data types are supported: + +* String - Everything is taken as a string. +* Boolean - Common representation of boolean values are accepted, including true, false, yes, no etc. +* Integer - Integer numbers only, can be negative. +* Real - Accept any numerical input. +* Array - A valid JSON or YAML input, that must evaluate to an array. +* Hash - A valid JSON or YAML input, that must evaluate to an object/map/dict/hash. +* YAML - Any valid YAML input. +* JSON - Any valid JSON input. + +There's no easy way to tell what type of data the Puppet manifest is expecting, so you will need to read through the code/documentation that comes with a particular module to find out. Changing the type field requires an appropriately set "Default Value" field. + +##### Complex data + +Here's an example of adding an array parameter. Note the use of YAML in the edit box: + +![Array](/static/images/screenshots/param_classes/1.14/array.png) + +This will be converted to the JSON `["a","b"]` syntax when you save. You can also use hashes in YAML or JSON as data types too. + +Note that the JSON hash syntax is not the same as Puppet's hash syntax: `{"example":"value"}` + +#### Input validation + +The *Optional input validator* section can be used to restrict the allowed values for the parameter. It is important to note that the validation applies to changes made from the Host edit page as well as the Puppet Classes edit page. + +The input validation section is hidden by default but can be opened by clicking on its title. When changing the parameter type this section will be automatically expanded to change the validations according to the new type. + + + + + + + + + + + +
Validator typeA combobox of data types. The type applies to the next field, the validator.
Validator ruleUsed to enforce certain values for the parameter values. See below for examples.
+ +For example, to restrict the "user" field to either "foreman" or "foremandev", tick the Required checkbox, and then set: + +* Type: List +* Rule: foreman,foremandev + +![Validators](/static/images/screenshots/param_classes/1.14/validators.png) + +##### String validators + +At present, the string type cannot be validated - leave the validator field blank, and all strings in the variable will be considered acceptable + +##### Regexp / List validators + +By entering a list (comma-separated, no spaces) or a regex (no delimiter required), the value to be assigned to the parameter will be checked against this list. If the value does not match the validator, and error will be raised. + +#### Template variables + +Because Foreman offers templating capabilities, you can utilise pre-existing variables, macros and or functions within your parameterized classes. This is especially useful if you need to send a string to Puppet, but have a need to embed host specific information within the string, such as the host's FQDN. + +Let's look a quick example situation: we need to configure RabbitMQ and have it use our existing Puppet SSL certs. Using what we've learnt above, we jump into the RabbitMQ class and configure the "ssl cert" parameter as such: + +![Template Variable](/static/images/screenshots/param_classes/1.14/template-variable-rabbit-ssl-cert.png) + +As you can see we're utilising a template variable within the parameter's string just like we would in a normal template file. The important part of this string, as we're sure you've gathered, is the "@host.name" element. This pulls the FQDN from Foreman's facts and inserts it into the string. + +More information regarding templates can be found in the [**Template Writing Reference**](https://docs.theforeman.org/{{ page.version }}/Managing_Hosts/index-foreman-el.html#Template_Writing_Reference_managing-hosts). This page also contains the [**pre-existing functions and macros you can use in your templates and parameter classes.**](https://docs.theforeman.org/{{ page.version }}/Managing_Hosts/index-foreman-el.html#Template_Macros_managing-hosts). + +#### Examples + +##### Example 1 - Simple change to a single host + +All our hosts use *server.foo* for something, except bob.domain.com which uses *server2.bar*: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parametertarget
DescriptionThe target server to talk to
Default Valueserver.foo
Type Validatorstring
Validator Constraint
Orderfqdn
hostgroup
os
domain
Attribute typefqdn = bob.domain.com
Valueserver2.bar
+ +##### Example 2 - Change for a group of hosts (via custom fact) with validation and ordering + +Most hosts need to use a port of *80* but all machines with a fact *region* and value *europe* need to use *8080*. To do this, you have to add the factname (in this example *region*) to the searchlist: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameterport
DescriptionThe port to use
Default Value80
Type Validatorlist
Validator Constraint80,443,8080
Orderfqdn
region
hostgroup
os
domain
Attribute typeregion = europe
Value8080
Attribute typefqdn = foo.domain
Value67
+ +Note that all machines will get either 80 or 8080 as required, except foo.domain which will generate an error, since 67 is not in the list validator. Note also that foo.domain will match before region, since it is higher in the searchlist. The rule ordering does not matter. + +It is also possible to mix conditions, e.g. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameterport
DescriptionThe port to use
Default Value80
Type Validatorlist
Validator Constraint80,443,8080
Orderfqdn
region, hostgroup, environment
hostgroup
environment
domain
Attribute typefqdn = foo.domain
Value67
Attribute typeregion, hostgroup, environment = europe, "web servers", production
Value8080
diff --git a/_includes/manuals/3.12/4.2_managing_puppet.md b/_includes/manuals/3.12/4.2_managing_puppet.md new file mode 100644 index 0000000000..f18c45f795 --- /dev/null +++ b/_includes/manuals/3.12/4.2_managing_puppet.md @@ -0,0 +1,2 @@ + +In this section we'll look at the various ways we can control and interact with Puppet. diff --git a/_includes/manuals/3.12/4.3.10_smartproxy_ssl.md b/_includes/manuals/3.12/4.3.10_smartproxy_ssl.md new file mode 100644 index 0000000000..a745fa634a --- /dev/null +++ b/_includes/manuals/3.12/4.3.10_smartproxy_ssl.md @@ -0,0 +1,71 @@ + +The smart proxy can work in SSL mode, where both sides verify and trust each other. Requests from Foreman will only be accepted if the SSL certificate can be verified. Since proxies abstract a high level of control over your infrastructure, the configuration and security of keys and certificates is important. + +#### Using Puppet CA certificates + +Since Foreman integrates with Puppet heavily, it is recommended to use the Puppet Certificate Authority (CA) to secure proxy access. See the _Security Communciations with SSL_ section for more advanced installations (multiple or internal CAs). + +If the smart proxy host is not managed by Puppet, you will need to generate a certificate - skip forward to the generate section. + +When using Puppet's certificates, the following lines will be required in puppet.conf to relax permissions to the `puppet` group. The `foreman` and/or `foreman-proxy` users should then be added to the `puppet` group. + +```ini +[main] +privatekeydir = $ssldir/private_keys { group = service } +hostprivkey = $privatekeydir/$certname.pem { mode = 640 } +``` + +##### Configuring the proxy + +Configure the locations to the SSL files in `/etc/foreman-proxy/settings.yml`, plus the list of trusted Foreman hosts: + +```yaml +:ssl_certificate: /etc/puppetlabs/puppet/ssl/certs/FQDN.pem +:ssl_ca_file: /etc/puppetlabs/puppet/ssl/certs/ca.pem +:ssl_private_key: /etc/puppetlabs/puppet/ssl/private_keys/FQDN.pem + +:trusted_hosts: +- foreman.corp.com +#- foreman.dev.domain +``` + +##### SSL cipher suites + +By default, the smart proxy permits the following SSL cipher suites: + +* ECDHE-RSA-AES128-GCM-SHA256 +* ECDHE-RSA-AES256-GCM-SHA384 +* AES128-GCM-SHA256 +* AES256-GCM-SHA384 +* AES128-SHA256 +* AES256-SHA256 +* AES128-SHA +* AES256-SHA + +Please note, the smart proxy uses the OpenSSL suite naming scheme. For more information on suite names please see [the OpenSSL docs](https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-SUITE-NAMES). + +Certain users may require to disable certain cipher suites due to security policies or newly discovered weaknesses. This can be done by using the `:ssl_disabled_ciphers:` option in `/etc/foreman-proxy/settings.yml`. For example: + +```yaml +:ssl_disabled_ciphers: ['AES128-SHA','AES256-SHA'] +``` + +##### Generating a certificate + +To generate a certificate for a proxy host that isn't managed by Puppet, do the following: + +1. Generate a new certificate on your puppetserver: `puppet cert --generate ` +2. Copy the certificates and key from the puppetserver to the smart proxy in `/etc/foreman-proxy`: + - /etc/puppetlabs/puppet/ssl/certs/ca.pem + - /etc/puppetlabs/puppet/ssl/certs/proxy-FQDN.pem + - /etc/puppetlabs/puppet/ssl/private_keys/proxy-FQDN.pem + +Follow the configuration section above, however use the `/etc/foreman-proxy` paths instead of the Puppet defaults. + +##### Configuring Foreman + +For Foreman to connect to an SSL-enabled smart proxy, it needs configuring with SSL certificates in the same way. If the Foreman system is managed by Puppet, it will already have these, else certificates can be generated following the above instructions. + +The locations of the certificates are managed in the *Settings* page, under *Provisioning* with the _ssl_ca_file_, _ssl_certificate_ and _ssl_priv_key_ settings. By default these will point to the Puppet locations - for manually generated certificates, or non-standard locations, they may have to be changed. + +Lastly, when adding the smart proxy in Foreman, ensure the URL begins with `https://` rather than `http://`. diff --git a/_includes/manuals/3.12/4.3.11_smartproxy_libvirt.md b/_includes/manuals/3.12/4.3.11_smartproxy_libvirt.md new file mode 100644 index 0000000000..e16eadfb32 --- /dev/null +++ b/_includes/manuals/3.12/4.3.11_smartproxy_libvirt.md @@ -0,0 +1,114 @@ +In this chapter, we will describe how to setup DHCP and DNS for use with the +libvirt provider for dnsmasq. + +This provider is able to change DHCP and DNS settings in libvirt with dnsmasq. +The smart proxy directly connects to the libvirt daemon. + + +The provider is currently limited by the libvirt API which does not provide +PTR records creation via the API itself, but dnsmasq automatically creates PTR +record for the first A/AAAA entry. Therefore PTR lookups do work in the +network, but it is not being created by Foreman orchestration. + +The provider also returns active leases on systems with `ruby-libvirt` gem +version 0.6.1 or higher. + +#### Configuration of libvirt + +Define the TFTP root first. Edit 'default' virtual network and add 'tftp', 'bootp' +and 'domain' elements. + +```xml + + default + 16b7b280-7462-428c-a65c-5753b84c7545 + + + + + + + + + + + + + + +``` + +Create a TFTP root directory, make sure it is writeable by the foreman proxy +user (`foreman-proxy` for instance) and accessible to the account +dnsmasq is running on (in Fedora this is `nobody`), set gid flag for newly +copied files and copy necessary files to the new TFTP root directory: + + mkdir -p /var/tftproot/{boot,pxelinux.cfg} + yum -y install syslinux + cp /usr/share/syslinux/{pxelinux.0,menu.c32,chain.c32} /var/tftproot + chown -R foreman-proxy:nobody /var/tftproot + find /var/tftproot/ -type d | xargs chmod g+s + +Open up `/etc/libvirt/libvirtd.conf` file and configure `foreman-proxy` user +to be able to connect to libvirt daemon: + + unix_sock_group = "foreman-proxy" + unix_sock_rw_perms = "0770" + +Alternatively (on development setups), you can turn off authentication: + + auth_unix_rw = "none" + +#### Configuration of smart-proxy + +Configure the Smart Proxy settings under config/ to: + +* enable tftp +* set correct tftp boot and set explicit tftp\_servername +* enable dns libvirt provider +* enable dhcp libvirt provider +* default settings for both providers are sufficient (network named `default` + on local libvirt daemon instance) + +Important configuration values are, in `tftp.yml`: + +```yaml +:tftp: true +:tftproot: /var/tftproot +:tftp_servername: 192.168.122.1 +``` + +in `dns.yml`: + +```yaml +:enabled: true +:use_provider: dns_libvirt +``` + +in `dhcp.yml`: + +```yaml +:enabled: true +:use_provider: dhcp_libvirt +``` + +and in `dns_libvirt.yml` and/or `dhcp_libvirt.yml`: + +```yaml +:network: default +:url: qemu:///system +``` + +#### Additional steps + +Make sure the DNS server is configured with the foreman instance by setting +`/etc/resolv.conf` file or changing this in NetworkManager or dnsmasq +configuration. Example: + + cat /etc/resolv.conf + nameserver 8.8.8.8 + nameserver 8.8.4.4 + nameserver 192.168.122.1 + +Foreman is now configured for libvirt provisioning, this is the recommended +setup for git development checkouts. diff --git a/_includes/manuals/3.12/4.3.12_smartproxy_templates.md b/_includes/manuals/3.12/4.3.12_smartproxy_templates.md new file mode 100644 index 0000000000..0d6089f2d8 --- /dev/null +++ b/_includes/manuals/3.12/4.3.12_smartproxy_templates.md @@ -0,0 +1,21 @@ +In this chapter, we will describe how to setup a Smart Proxy to serve +provisioning templates. + +The smart proxy is able to proxy template requests from hosts in isolated +networks to the Foreman server, when the proxy also handles TFTP. + +This feature relies on correctly [configured trusted_proxies]({{ site.baseurl }}manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) on Foreman. + +
Generally, you want the templates to be available on HTTP as well as HTTPS. When enabling HTTP on your smart proxy, ensure that other modules' configurations in /etc/foreman-proxy/settings.d/*.yml are secure by setting :enabled: to https instead of true.
+ +Ensure the foreman_url in `/etc/foreman-proxy/settings.yaml` points to your Foreman instance, and that your smart proxy is listening on HTTP by uncommenting `http_port`. Now +configure `/etc/foreman-proxy/settings.d/templates.yml`: + +```yaml +:enabled: true +:template_url: http://smart-proxy.example.com:8000 +``` + +Once you've completed the above steps, restart the foreman-proxy service and refresh the features on your Foreman server. + +The templates feature is used automatically: any host that uses this proxy for TFTP will also use the proxy to retrieve its templates. diff --git a/_includes/manuals/3.12/4.3.13_smartproxy_logs.md b/_includes/manuals/3.12/4.3.13_smartproxy_logs.md new file mode 100644 index 0000000000..38286049ef --- /dev/null +++ b/_includes/manuals/3.12/4.3.13_smartproxy_logs.md @@ -0,0 +1,11 @@ +The smart proxy's logs module provides an API to retrieve recently logged messages and information about failed modules. This will be displayed in Foreman under the Smart Proxy pages when the module is enabled. + +The module has no configuration options of its own, and is just enabled by configuring `/etc/foreman-proxy/settings.d/logs.yml`: + +```yaml +:enabled: https +``` + +Once enabled, restart the foreman-proxy service and refresh the features on your Foreman server. + +The number of logs is controlled by the main smart proxy logging settings, detailed in [Smart Proxy Settings](/manuals/{{page.version}}/index.html#4.3.2SmartProxySettings). diff --git a/_includes/manuals/3.12/4.3.1_smartproxy_installation.md b/_includes/manuals/3.12/4.3.1_smartproxy_installation.md new file mode 100644 index 0000000000..970a74f9a6 --- /dev/null +++ b/_includes/manuals/3.12/4.3.1_smartproxy_installation.md @@ -0,0 +1,105 @@ + +A smart proxy is an autonomous web-based foreman component that is placed on a host performing a specific function in the host commissioning phase. +It receives requests from Foreman to perform operations that are required +during the commissioning process and executes them on its behalf. More details +can be found on the [**Foreman Architecture**](manuals/{{page.version}}/index.html#ForemanArchitecture) page. + +To fully manage the commissioning process then a smart proxy will have to manipulate these services, DHCP, DNS, Puppet CA, Puppet and TFTP. These services may exist on separate machines or several of them may be hosted on the same machine. As each smart proxy instance is capable of managing all the of these services, there is only need for one proxy per host. +In the special case of a smart proxy managing a Windows DHCP server, the host machine must be running Windows, it does not need to be the Microsoft DHCP server itself. + +#### Packages + +RPM and Debian packages are available, see the [Install from Packages](manuals/{{page.version}}/index.html#3.3InstallFromPackages) section for configuration and install the `foreman-proxy` package. + +#### Source code + +You can get the latest stable code from [GitHub](https://github.com/theforeman/smart-proxy) ([via git](git://github.com/theforeman/smart-proxy.git)). + +``` +git clone git://github.com/theforeman/smart-proxy.git -b {{page.version}}-stable +``` + +#### System requirements + +The smart proxy will run with the following requirements (aside from rubygem dependencies): + +* Ruby 2.5, 2.6 or 2.7 + +#### Windows +The Microsoft smart-proxy installation procedure is very basic compared to the RPM or APT based solution. You need to run smart-proxy from the source as well as install Ruby and Ruby DevKit. + +1. Run [Ruby Installer](http://rubyinstaller.org/downloads/) and add the matching DevKit to compile native extensions. Make sure to add Ruby to `%PATH%`, you can select this option in the installer +1. Download / clone the [smart proxy repository](https://github.com/theforeman/smart-proxy) to a convenient location (see above, _Source Code_). Make sure to download / checkout the maching branch to your foreman installation +1. Open a command prompt (`cmd.exe`) and run the following commands in order: + 1. `ruby \dk.rb init` + 1. `ruby \dk.rb install` + 1. `gem install --no-ri --no-rdoc bundler` + 1. `cd ` + 1. `bundle install --without development test krb5 puppet_proxy_legacy bmc libvirt` + +##### General configuration +1. Create the SSL certificate and key + 1. Login to your puppetserver + 1. On the command line, type the following command. Take care not to use an alias nor upper case characters. + + puppet cert generate new-smart-proxy-FQDN + + 1. Copy the private key, the public certificate and the ca.pem from /var/lib/puppet/ssl on your puppetserver over to a location accessible by your new smart proxy, e.g. `\ssl\` (create the directory if necessary - this location will be referred to by the settings.yml in the next step) +1. Copy *settings.yml.example* inside *config* to *settings.yml* +1. At very least, modify the settings for `:bind_host:` and `:log_file:` and SSL, for example: + +```yaml +:bind_host: '0.0.0.0' +:log_file: 'C:\smart-proxy.log' + +:trusted_hosts: [ foreman.example.com ] + +:ssl_certificate: \ssl\host.example.com.pem +:ssl_private_key: \ssl\host.example.com.pem +:ssl_ca_file: \ssl\ca.pem +``` + +##### Test and configure smart proxy features +1. Test your configuration by setting `:log_level: DEBUG` and `:log_file: STDOUT` in *config/settings.yml* +1. Open an administrative command prompt and run `bundle exec ruby \bin\smart-proxy` +1. [Configure smart-proxy features like DNS and DHCP](manuals/{{page.version}}/index.html#4.3.2SmartProxySettings) +1. Once everything runs well install a Windows service using `ruby extra\register_service.rb` to register the service `Foreman Smart Proxy`. Alternatively, use a third party tool like [NSSM](https://nssm.cc/) to create the service. + +__Caveats:__ There is an issue with DevKit not finding any ruby version installed. Check that the DevKit and Ruby Installer are both x32 or x64, otherwise [add the missing versions manually by editing `config.yml`](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit#4-run-installation-scripts). + +__Puppet hint:__ If you have Puppet installed on the same host running smart-proxy, you can use Puppet's Ruby. You only need DevKit. In this case, just add directory containing `ruby.exe` to your path variable and add it to DevKit settings if necessary by editing DevKit's `config.yml`. Also, you might want to use Puppet's host certificates right away for smart proxy SSL connections. Usually, they can be found in `C:\ProgramData\PuppetLabs\puppet\etc\ssl`. For example: + +```yaml +:ssl_certificate: C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\host.example.com.pem +:ssl_private_key: C:\ProgramData\PuppetLabs\puppet\etc\ssl\private_keys\host.example.com.pem +:ssl_ca_file: C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem +``` + +#### Configuration file + +Usually can be found at /etc/foreman-proxy/settings.yml or in the config/settings.yml subdirectory. +You can use the *settings.yml.example* file inside the *config* directory as a template for your own *settings.yml*. + +Configuration of each subsystem is usually in /etc/foreman-proxy/settings.d/ or in the config/settings.d/ subdirectory. If you don't plan to use one of the subsystems, please disable them in these configuration files. For more information see [**Smartproxy Configuration**](manuals/{{page.version}}/index.html#4.3.2SmartProxySettings). + +#### Start the daemon + +``` +bundle exec bin/smart-proxy +``` + +Or if you installed it via a package simply start the foreman-proxy service. + +``` +service foreman-proxy start +``` + +#### Add the Smart Proxy to Foreman + +* Go to Foreman, under *Infrastructure > Smart proxies*, click *New Proxy* +* Type in the Name for your Proxy and the URL of your Proxy, with the port used + +For example: + +* Name: Puppet-Proxy +* URL: http://puppet.your-domain.com:8443 diff --git a/_includes/manuals/3.12/4.3.2_smartproxy_settings.md b/_includes/manuals/3.12/4.3.2_smartproxy_settings.md new file mode 100644 index 0000000000..f0e46db08f --- /dev/null +++ b/_includes/manuals/3.12/4.3.2_smartproxy_settings.md @@ -0,0 +1,125 @@ +The main configuration for the core Smart Proxy is held in the */etc/foreman-proxy/settings.yml* or *config/settings.yml* file. This includes configuration of ports to listen on, SSL and security settings and logging options. + +Each of the modules used in the Smart Proxy have their configuration in the */etc/foreman-proxy/settings.d/* or *config/settings.d* directory. Modules are enabled or disabled inside their respective configuration files with the `:enabled` directive, which determines whether the module is available on HTTP, HTTPS, both or is disabled (see below for more details). + +#### YAML start + +The first non-comment line of all configuration files must be three dashes. + +```yaml +--- +``` + +#### Logging (settings.yml) + +The proxy's output is captured to the **log_file** and may be filtered via the usual Unix syslog levels: + +* *WARN* +* *DEBUG* +* *ERROR* +* *FATAL* +* *INFO* +* *UNKNOWN* + +See Ruby's [Logger class](http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/classes/Logger.html) for details. + +```yaml +:log_file: /var/log/foreman-proxy/proxy.log +:log_level: DEBUG +``` + +The log_file setting may be set to "STDOUT" which causes log messages to be logged to standard output, for capture by the running process (e.g. systemd with journal). When log_file is set to "SYSLOG", all messages will be sent to syslog. + +A limited number of recent log messages are kept in memory using a ring buffer, which can be exposed in the API and to Foreman by enabling the [Logs feature](/manuals/{{page.version}}/index.html#4.3.13Logs). + +The number of all log messages is controlled by the `log_buffer` setting, and a second buffer of error messages is controlled by the `log_buffer_errors` setting. The total of the two will directly affect the maximum amount of memory used, which is approximately 500kB in the default configuration of 3,000 recent messages. + +```yaml +:log_buffer: 2000 +:log_buffer_errors: 1000 +``` + +#### Listening configuration (settings.yaml) + +By default the Smart Proxy listens on all interfaces, which can be changed to limit access to a network: + +```yaml +# host to bind ports to (possible values: *, localhost, 0.0.0.0) +:bind_host: ['*'] +:bind_host: private.example.com +:bind_host: 192.168.1.10 +``` + +The Smart Proxy has a number of different modules which can be enabled either for HTTP, for HTTPS or for access on both services. It is highly recommended to enable most only on HTTPS and only enable modules on HTTP when required (e.g. templates) or if no SSL is desired. + +The two port options control which TCP port(s) the Smart Proxy will listen on. At least one must be enabled for the proxy to start. It is recommended to only set https_port unless an HTTP-only module is active, which also requires the three ssl_* settings to be set. + +```yaml +:http_port: 8000 +:https_port: 8443 +``` + +
Be careful when enabling http_port, ensure settings.d/ files are enabled only on HTTPS or trusted_hosts is set appropriately so modules are not exposed without security on HTTP.
+ +Modules are enabled in their per-module configuration file in */etc/foreman-proxy/settings.d/* with the `:enabled` directive, which can be set to: + +* `:enabled: false` to disable the module entirely +* `:enabled: http` to listen on HTTP only +* `:enabled: https` to listen on HTTPS only (recommended) +* `:enabled: true` to listen on both HTTP and HTTPS if enabled (not recommended) + +#### Security configuration (settings.yml) + +The existence of all the three ssl key entries below requires the use of an SSL connection. + +**NOTE** that both client certificates need to be signed by the same CA, which must be in the *ssl_ca_file*, in order for this to work +see [**SSL**](manuals/{{page.version}}/index.html#4.3.10SSL) for more information + +```yaml +:ssl_certificate: ssl/certs/fqdn.pem +:ssl_ca_file: ssl/certs/ca.pem +:ssl_private_key: ssl/private_keys/fqdn.key +``` + +Specific SSL cipher suites can be disabled by using the `:ssl_disabled_ciphers:` option. For more information on which cipher suites are enabled by default and how to correctly disable specific ones, please see [**SSL cipher suites**](manuals/{{page.version}}/index.html#ssl-cipher-suites). + +The TLS versions can be disabled if requiring a specific version. SSLv3, TLS v1.0, and TLS v1.1 are disabled by default, setting the array of `:tls_disabled_versions:` to include `1.2` will disable this version, too. + +This is the list of hosts from which the smart proxy will accept connections. For HTTPS connections, the name must match the common name (CN) within the subject DN and for HTTP connections, it must match the hostname from reverse DNS. + +```yaml +:trusted_hosts: + - foreman.prod.domain + - foreman.dev.domain +``` + +For HTTPS connections, the name must match the common name (CN) within the subject DN and for HTTP connections, it must match the hostname from reverse DNS. When `:forward_verify` is enabled (default: true) then the reverse lookup is verified against the forward lookup of the hostname (aka forward-confirmed reverse DNS/FCrDNS). + +Some modules may allow connections from all hosts rather than only the trusted_hosts list, particularly if they intend to deal with requests directly from managed hosts rather than only from Foreman. + +An empty trusted_hosts list will permit no hosts access: + +```yaml +:trusted_hosts: [] +``` + +While if the setting is not specified, any host may make requests to the smart proxy, which permits management of any enabled modules and features. + +#### Foreman communication (settings.yml) + +Some modules make requests *back* to Foreman, e.g. when relaying requests from client hosts. The following setting changes the destination URL: + +```yaml +:foreman_url: https://foreman.example.com +``` + +And the following settings change the SSL certificates used to authenticate to Foreman and to verify its certificate. In a typical installation, Foreman and the Smart Proxy may both use certificates signed the same certificate authority, so these default to the values of the ssl_* settings defined above. + +```yaml +# SSL settings for client authentication against Foreman. If undefined, the values +# from general SSL options are used instead. Mainly useful when Foreman uses +# different certificates for its web UI and for smart-proxy requests. +:foreman_ssl_ca: /etc/foreman-proxy/ssl/certs/ca.pem +:foreman_ssl_cert: /etc/foreman-proxy/ssl/certs/fqdn.pem +:foreman_ssl_key: /etc/foreman-proxy/ssl/private_keys/fqdn.pem +``` diff --git a/_includes/manuals/3.12/4.3.3.1_smartproxy_bmc_ssh.md b/_includes/manuals/3.12/4.3.3.1_smartproxy_bmc_ssh.md new file mode 100644 index 0000000000..d6888603a0 --- /dev/null +++ b/_includes/manuals/3.12/4.3.3.1_smartproxy_bmc_ssh.md @@ -0,0 +1,20 @@ + +The SSH BMC provider provides a limited level of BMC functionality by running commands over an SSH connection to the host using a trusted SSH key. + +It has the following configuration options for authentication, for the remote SSH user and private SSH key: + +```yaml +:bmc_ssh_user: root +:bmc_ssh_key: /usr/share/foreman/.ssh/id_rsa +``` + +The following configuration options control the commands executed by the provider on the remote host: + +```yaml +:bmc_ssh_powerstatus: "true" +:bmc_ssh_powercycle: "shutdown -r +1" +:bmc_ssh_poweroff: "shutdown +1" +:bmc_ssh_poweron: "false" +``` + +No power on support is possible with this provider. diff --git a/_includes/manuals/3.12/4.3.3_smartproxy_bmc.md b/_includes/manuals/3.12/4.3.3_smartproxy_bmc.md new file mode 100644 index 0000000000..564355dc24 --- /dev/null +++ b/_includes/manuals/3.12/4.3.3_smartproxy_bmc.md @@ -0,0 +1,16 @@ + +Activate the BMC management module within the Smart Proxy instance. This allows users to trigger power management commands through the proxy to controlled hosts using IPMI or similar. + +```yaml +:enabled: https +:bmc_default_provider: freeipmi +``` + +Available providers are: + +* `freeipmi` - for IPMI control using the freeipmi implementation +* `ipmitool` - using the ipmitool implementation +* `shell` - specialized provider for controlling the proxy server itself (used for Foreman Discovery) +* `ssh` - simple provider via SSH command `shutdown` with limited functionality (poweron does not work) + +The credentials and addresses used to control hosts are passed from Foreman itself by adding a new network interface with the type set to "BMC" to hosts. diff --git a/_includes/manuals/3.12/4.3.4.2_isc_dhcp.md b/_includes/manuals/3.12/4.3.4.2_isc_dhcp.md new file mode 100644 index 0000000000..f98db5a668 --- /dev/null +++ b/_includes/manuals/3.12/4.3.4.2_isc_dhcp.md @@ -0,0 +1,77 @@ +ISC implementation is based on the OMAPI interface, which means: + +* No need for root permissions on your DHCP server +* No need to restart (or "sync") your DHCP server after every modifications. + +##### Configuration + +* dhcpd configuration file: +ensure you have the following line in your dhcpd.conf file (somewhere in the top first lines): +`omapi-port 7911;` +* configure the settings file to point to your dhcpd.conf and dhcpd.leases files (make sure they are readable by the smart-proxy user) +* make sure the omshell command (/usr/bin/omshell) can be executed by the smart-proxy user. +* make sure that /etc/dhcp and /etc/dhcp/dhcpd.conf has group foreman-proxy + + +##### Securing the dhcp API + +The dhcpd api server will listen to any host. You might need to add a omapi_key to provide basic security. + +Example generating a key (on CentOS): +``` +yum install bind +dnssec-keygen -r /dev/urandom -a HMAC-MD5 -b 512 -n HOST omapi_key +cat Komapi_key.+*.private |grep ^Key|cut -d ' ' -f2- +``` + +1. Edit your "/etc/dhcpd.conf": + +``` +omapi-port 7911; +key omapi_key { +algorithm HMAC-MD5; + secret "XXXXXXXXX"; #<-The output from the generated key above. +}; +omapi-key omapi_key; +``` + +2. Make sure you also add the omapi_key to your proxy's [dhcp_isc.yml](/manuals/{{page.version}}/index.html#4.3.4DHCP) + +3. Restart the dhcpd and foreman-proxy services + +**NOTE**: if you don't see DHCP in Smart Proxies Features, choose "Refresh features" from drop-down menu. + +The next step is to set up appropriate Subnets in Foreman from the settings menu. + +##### Sample dhcpd.conf +``` +ddns-update-style interim; +ignore client-updates; +authoritative; +allow booting; +allow bootp; + +omapi-port 7911; +#Optional key: +key omapi_key { + algorithm HMAC-MD5; + secret "2wgoV3yukKdKMkmOzOn/hIsM97QgLTT4CLVzg9Zv0sWOSe1yxPxArmr7a/xb5DOJTm5e/9zGgtzL9FKna0NWis=="; +} +omapi-key omapi_key; + +subnet 10.1.1.0 netmask 255.255.255.0 { +# --- default gateway + option routers 10.1.1.254; + option subnet-mask 255.255.255.0; + + option domain-name "domain.com"; + option domain-name-servers 10.1.1.1, 8.8.8.8; + option log-servers syslog; + option ntp-servers ntp; + + range dynamic-bootp 10.1.1.10 10.1.1.250; + default-lease-time 21600; + max-lease-time 43200; + +} +``` diff --git a/_includes/manuals/3.12/4.3.4.3_ms_dhcp.md b/_includes/manuals/3.12/4.3.4.3_ms_dhcp.md new file mode 100644 index 0000000000..e05bd6840d --- /dev/null +++ b/_includes/manuals/3.12/4.3.4.3_ms_dhcp.md @@ -0,0 +1,26 @@ +It is required that this procedure is executed as an administrator. + +It is not required that the smart proxy be on the same host as the MS DHCP server. The smart proxy just needs to be on a Windows host with connectivity to the DHCP server. If this is the case, make sure the smart proxy service runs as a user with sufficient privileges. + +__Note:__ Refer to the [installation guide](manuals/{{page.version}}/index.html#4.3.1SmartProxyInstallation) for general setup. + +1. Edit config/settings.d/dhcp.yml so that it looks a bit like this. `:server:` can be left commented out if smart proxy runs on the same host. + + _Sample config/settings.d/dhcp.yml file_ + + --- + # Can be true, false, or http/https to enable just one of the protocols + :enabled: https + :use_provider: dhcp_native_ms + :server: 10.10.10.1 + +2. If needed, you have to create the option 60 on the Windows DHCP (for PXE Boot) + + - Open an administrator command prompt + - Create the PXE Option using netsh + + C:\Windows\system32>netsh + netsh>dhcp + netsh dhcp> server 10.10.10.1 + netsh dhcp server>add optiondef 60 PXEClient String 0 comment= PXE Support + diff --git a/_includes/manuals/3.12/4.3.4_smartproxy_dhcp.md b/_includes/manuals/3.12/4.3.4_smartproxy_dhcp.md new file mode 100644 index 0000000000..aeac3684e5 --- /dev/null +++ b/_includes/manuals/3.12/4.3.4_smartproxy_dhcp.md @@ -0,0 +1,109 @@ + +Activate the DHCP management module within the Smart Proxy instance. This is used to query for available IP addresses (looking at existing leases and reservations), add new and delete existing reservations. It cannot manage subnet declarations, which should be managed by another means (e.g. [puppet-dhcp](https://github.com/theforeman/puppet-dhcp)). + +The DHCP module is capable of managing the ISC DHCP server, Microsoft Active Directory and Libvirt instances. + +Builtin providers are: + +* `dhcp_isc` - ISC DHCP server over OMAPI +* `dhcp_libvirt` - dnsmasq DHCP via libvirt API +* `dhcp_native_ms` - Microsoft Active Directory using API + +Extra providers are available as plugins and can be installed through packages. See the following pages for more information: + +* [List of smart proxy plugins](http://projects.theforeman.org/projects/foreman/wiki/List_of_Smart-Proxy_Plugins) +* [Plugin installation documentation]({{ site.baseurl }}plugins/) + +To enable the DHCP module and enable a provider, `dhcp.yml` must contain: + +```yaml +:enabled: https +:use_provider: dhcp_isc +``` + +For providers from plugins, check the plugin documentation to determine the exact provider name. + +The module manages a DHCP server on the local host by default, but for providers that can be run remotely, the server address can be changed: + +```yaml +:server: 127.0.0.1 +``` + +Note that if the DHCP server is running remotely, some providers (notably ISC) require that the configuration files must be accessible to the Smart Proxy still. This can be achieved with a network file system, e.g. NFS. + +All available subnets will be loaded and can be managed by default, but this can have a performance penalty. If only some subnets are used, specify them as follows in `network_address/network_mask` notation: + +```yaml +:subnets: [192.168.205.0/255.255.255.128, 192.168.205.128/255.255.255.128] +``` + +Each provider has its own configuration file in the same directory with its own settings, e.g. `dhcp_isc.yml`. This usually needs additional configuration after changing the `use_provider` setting. + +#### dhcp_isc + +The dhcp_isc provider uses a combination of the ISC DHCP server OMAPI management interface and parsing of configuration and lease files. This requires it to be run either on the same host as the DHCP server or to have network filesystem access to these files. + +This provider requires the `config` and `leases` settings in the `dhcp_isc.yml` configuration file, which should be set to the location of the DHCP server config and lease files. On a Red Hat or Fedora server use: + +```yaml +:config: /etc/dhcp/dhcpd.conf +:leases: /var/lib/dhcpd/dhcpd.leases +``` + +On a Debian or Ubuntu DHCP server, use the following values instead: + +```yaml +:dhcp_config: /etc/dhcp3/dhcpd.conf +:dhcp_leases: /var/lib/dhcp3/dhcpd.leases +``` + +
The foreman-proxy account must be able to read both configuration files. In particular, check the permissions on the parent directory (e.g. /etc/dhcp) permit world read/execute.
+ +If the DHCP server is secured with an "omapi_key", the following entries must be set with the same values: + +```yaml +:key_name: omapi_key +:key_secret: XXXXXXXX +``` + +If the DHCP server is listening on a non-standard OMAPI port (i.e. not 7911), then change this with: + +```yaml +:omapi_port: 7911 +``` + +For DHCP servers running on a different host, change `:server` in the main `dhcp.yml` configuration file. + +#### dhcp_native_ms + +The native_ms provider manages reservations in Microsoft Active Directory via its native API. + +Possible configuration options in `dhcp_native_ms.yml` are: + +```yaml +:disable_ddns: true +``` + +When `disable_ddns` is true (default), dynamic DNS updates will be disabled for all hosts that the smart proxy creates. This will slightly slow the host creation process but will ensure that the DHCP server will not create or delete DNS entries on behalf of these clients. It's preferable to disable this feature at the scope level. + +#### dhcp_libvirt + +Provider that manages reservations and leases via dnsmasq through libvirt API. +It uses ruby-libvirt gem to connect to the local or remote instance of libvirt +daemon. + +Possible configuration options in `dhcp_libvirt.yml` are: + +```yaml +# Libvirt network. Only one network is supported. +:network: default + +# Libvirt connection. Make sure proxy effective user have permission to connect. +:url: qemu:///system +``` + +When configuring local or remote connections, make sure the `foreman-proxy` +effective user has UNIX permissions to libvirt socket or ssh keys are +deployed when using remote connection. + +More information about using this provider is in the [Libvirt section]({{ site.baseurl }}manuals/{{ page.version }}/index.html#4.3.11Libvirt). diff --git a/_includes/manuals/3.12/4.3.5.2_bind.md b/_includes/manuals/3.12/4.3.5.2_bind.md new file mode 100644 index 0000000000..52c14567a0 --- /dev/null +++ b/_includes/manuals/3.12/4.3.5.2_bind.md @@ -0,0 +1,37 @@ + +Bind configuration manipulation is based on nsupdate, which means that in theory could also be used to manipulate other dns servers which support nsupdate (such as Microsoft DNS server). + +#### Configuration + +In order to communicate securely with your dns server, you would need a key which will be used by nsupdate and your named daemon using ddns-confgen or dnssec-keygen + +#### example using ddns-confgen + +execute 'ddns-confgen -k foreman -a hmac-md5' - this should output something like the following: + +``` +# To activate this key, place the following in named.conf, and +# in a separate keyfile on the system or systems from which nsupdate +# will be run: +key "foreman" { + algorithm hmac-md5; + secret "GGd1oNCxaKsh8HA84sP1Ug=="; +}; + +# Then, in the "zone" statement for each zone you wish to dynamically +# update, place an "update-policy" statement granting update permission +# to this key. For example, the following statement grants this key +# permission to update any name within the zone: +update-policy { + grant foreman zonesub ANY; +}; + +# After the keyfile has been placed, the following command will +# execute nsupdate using this key: +nsupdate -k /path/to/keyfile +``` + +You should create a new file (such as /etc/rndc.key or other) and store the key "foreman {...} in it. +in the proxy Settings file you should point to this file location - make sure that the proxy have read permissions to this file. + +In your named file, you could add the update-policy statement or something like this [named example file](http://theforeman.org/projects/smart-proxy/wiki/Named_example_file) if you need more fine grained permissions. diff --git a/_includes/manuals/3.12/4.3.5.3_gsstsig.md b/_includes/manuals/3.12/4.3.5.3_gsstsig.md new file mode 100644 index 0000000000..413d62a20c --- /dev/null +++ b/_includes/manuals/3.12/4.3.5.3_gsstsig.md @@ -0,0 +1,81 @@ +Both BIND as configured in FreeIPA and Microsoft AD DNS servers can accept DNS updates using GSS-TSIG authentication. This uses Kerberos principals to authenticate to the DNS server. Under Microsoft AD, this is known as "Secure Dynamic Update". + +#### Pre-requisites + +* Kerberos principal in the realm/domain that Smart Proxy can use +* Kerberos keytab for the above principal +* Access to add/delete/modify the required zones in Microsoft DNS. Both forward and reverse lookup. + +#### Microsoft AD configuration + +A user has to be created in Active Directory that will be used by the Smart Proxy, e.g. `foremanproxy`. This will automatically create a service principal, e.g. `foremanproxy@EXAMPLE.COM`. + +Test the Kerberos login with that user on the Smart Proxy using kinit: + + kinit foremanproxy@EXAMPLE.COM + +This requires that your SRV records in DNS or /etc/krb5.conf file is setup correctly. By default many systems use DNS to locate the Kerberos DC. A KDC can also be statically set in this file. There are dozens of documents on how to do this on the net. + +If login works, the keytab file can be created using `ktutil`. First clear the Kerberos ticket cache: + + kdestroy + +Now create the keytab file with `ktutil`: + + ktutil: addent -password -p foremanproxy@EXAMPLE.COM -k 1 -e RC4-HMAC + ktutil: wkt dns.keytab + ktutil: q + +Once the keytab file has been created, test it using kinit: + + kinit foremanproxy@EXAMPLE.COM -k -t dns.keytab + +If this works, clear the Kerberos ticket cache once again using `kdestroy`. + +Store the keytab at `/etc/foreman-proxy/dns.keytab`, ensure permissions are 0600 and the owner is `foreman-proxy`. +If you are using SELinux, do not forget to update the file context. + +The DNS zone `Dynamic Updates` option on the DNS zones can now be set to `Secure Only`. + +Restart the smart proxy service. Next, go to Update the configuration in Foreman. + +#### FreeIPA configuration + +A service principal is required for the Smart Proxy, e.g. `foremanproxy/proxy.example.com@EXAMPLE.COM`. + +First of all, create a new principal (FreeIPA service) for Foreman, e.g. `ipa service-add foremanproxy/proxy.example.com@EXAMPLE.COM`. + +Then fetch the keytab, e.g. `ipa-getkeytab -p foremanproxy/proxy.example.com@EXAMPLE.COM -s ipa-server.example.com -k /etc/foreman-proxy/dns.keytab`. + +Store the keytab at `/etc/foreman-proxy/dns.keytab`, ensure permissions are 0600 and the owner is `foreman-proxy`. + +The ACL on updates to the DNS zone then needs to permit the service principal. In the FreeIPA web UI, under the DNS zone, go to the Settings tab, verify that "Dynamic update" for that zone is set to "True", and add to the BIND update policy a new grant: + + grant foremanproxy\047proxy.example.com@EXAMPLE.COM wildcard * ANY; + +Note the `\047` is written verbatim, and don't forget the semicolon. ACLs should be updated for both forward and reverse zones as desired. + +#### Proxy configuration + +Update the proxy DNS configuration file (`/etc/foreman-proxy/settings.d/dns.yml`) with the following setting: + +```yaml +:use_provider: dns_nsupdate_gss +``` + +And the DNS GSS configuration file (`/etc/foreman-proxy/settings.d/dns_nsupdate_gss.yml`) with: + +```yaml +:dns_tsig_keytab: /etc/foreman-proxy/dns.keytab +:dns_tsig_principal: foremanproxy/proxy.example.com@EXAMPLE.COM +``` + +Ensure the `dns_key` setting is not specified, or is commented out. + +Restart the smart proxy service. Next, go to Update the configuration in Foreman. + +#### Update the configuration in Foreman + +After you have added a DNS smart proxy, you must instruct Foreman to rescan the configuration on each affected smart proxy by using the drop-down menu by its name and selecting "Refresh Features". + +Now, you are allowed to enable this in each subnet (reverse lookup of domain) and domain (forward lookup of domain) that you want this smart proxy to assist. You do this by navigating there and selecting it in the drop-down menu for DNS. diff --git a/_includes/manuals/3.12/4.3.5_smartproxy_dns.md b/_includes/manuals/3.12/4.3.5_smartproxy_dns.md new file mode 100644 index 0000000000..b74f72fe33 --- /dev/null +++ b/_includes/manuals/3.12/4.3.5_smartproxy_dns.md @@ -0,0 +1,110 @@ + +Activate the DNS management module within the Smart Proxy instance. This is used to update and remove DNS records from existing DNS zones. + +The DNS module can manipulate any DNS server that complies with the ISC Dynamic DNS Update standard and can therefore be used to manage both Microsoft Active Directory and BIND servers. Updates can also be made using GSS-TSIG, see the second section below. Additional providers are available for managing libvirt's embedded DNS server (dnsmasq) and Microsoft Active Directory using dnscmd, for static DNS records, avoiding scavenging. + +Builtin providers are: + +* `dns_nsupdate` - dynamic DNS update using nsupdate +* `dns_nsupdate_gss` - dynamic DNS update with GSS-TSIG +* `dns_libvirt` - dnsmasq DNS via libvirt API +* `dns_dnscmd` - static DNS records in Microsoft Active Directory + +Extra providers are available as plugins and can be installed through packages. See the following pages for more information: + +* [List of smart proxy plugins](http://projects.theforeman.org/projects/foreman/wiki/List_of_Smart-Proxy_Plugins) +* [Plugin installation documentation]({{ site.baseurl }}plugins/) + +To enable the DNS module and enable a provider, `dns.yml` must contain: + +```yaml +:enabled: https +:use_provider: dns_nsupdate +``` + +For providers from plugins, check the plugin documentation to determine the exact provider name. + +The default TTL of DNS records added by the Smart Proxy is 86400 seconds (one day). This can be changed with the dns_ttl setting: + +```yaml +:dns_ttl: 86400 +``` + +Each provider has its own configuration file in the same directory with its own settings, e.g. `dns_nsupdate.yml`. This usually needs additional configuration after changing the `use_provider` setting. + +#### dns_nsupdate + +The dns_nsupdate provider uses the `nsupdate` command to make dynamic updates to the DNS server records. This works on a wide variety of RFC2136-compliant servers. + +DNS servers that support Kerberos authentication, e.g. FreeIPA or Microsoft Active Directory, should use the dns_nsupdate_gss provider instead. + +This provider has the following settings in the `dns_nsupdate.yml` configuration file: + +```yaml +#:dns_key: /etc/rndc.key +:dns_server: localhost +``` + +The **dns_key** specifies a file containing a shared secret used to generate a signature for the update request (TSIG record), thus authenticating the smart proxy to the DNS server. + +
If you use a key file or keytab, make sure that only the foreman-proxy account can read that file.
+ +If neither the **dns_key** or GSS-TSIG is used then the update request is sent without any signature. Unsigned update requests are considered insecure. Some DNS servers can be configured to accept only signed signatures. + +The **dns_server** option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed. + +```yaml +:dns_key: /etc/foreman-proxy/Kapi.+157+47848.private +:dns_server: dnsserver.site.example.com +``` + +#### dns_nsupdate_gss + +For servers that support Kerberos/GSS-TSIG to authenticate DNS updates, the dns_nsupdate_gss provider should be used. This typically applies to FreeIPA and Microsoft Active Directory servers. This is equivalent to the `nsupdate -g` command. + +This provider has the following settings in the `dns_nsupdate_gss.yml` configuration file: + +```yaml +:dns_tsig_keytab: /usr/share/foreman-proxy/dns.keytab +:dns_tsig_principal: DNS/host.example.com@EXAMPLE.COM +``` + +See the section on GSS-TSIG DNS below for steps on setting up the requisite accounts and keytabs with both AD and FreeIPA. + +The **dns_server** option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed. + +```yaml +:dns_server: dnsserver.site.example.com +``` + +#### dns_dnscmd + +While the `dns_nsupdate` provider creates dynamic records in Active Directory, the `dns_dnscmd` provider uses the `dnscmd` tool to create static DNS records in AD, which are not affected by scavenging. This requires that the Smart Proxy is installed on a Windows server with `dnscmd` available. + +The **dns_server** option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed. + +```yaml +:dns_server: dnsserver.site.example.com +``` + +#### dns_libvirt + +Provider that manages reservations and leases via dnsmasq through libvirt API. +It uses ruby-libvirt gem to connect to the local or remote instance of libvirt +daemon. + +Possible configuration options in `dns_libvirt.yml` are: + +```yaml +# Libvirt network. Only one network is supported. +:network: default + +# Libvirt connection. Make sure proxy effective user have permission to connect. +:url: qemu:///system +``` + +When configuring local or remote connections, make sure the `foreman-proxy` +effective user has UNIX permissions to libvirt socket or ssh keys are +deployed when using remote connection. + +More information about using this provider is in the [Libvirt section]({{ site.baseurl }}manuals/{{ page.version }}/index.html#4.3.11Libvirt). diff --git a/_includes/manuals/3.12/4.3.6_smartproxy_puppet.md b/_includes/manuals/3.12/4.3.6_smartproxy_puppet.md new file mode 100644 index 0000000000..b83f23ac23 --- /dev/null +++ b/_includes/manuals/3.12/4.3.6_smartproxy_puppet.md @@ -0,0 +1,56 @@ +Activate the Puppet management module within the Smart Proxy instance. This module has two functions: + +* Report the Puppet environments and Puppet classes with their parameters from the Puppetserver. Used when importing classes into Foreman +* Optionally trigger immediate Puppet runs on clients using one of a number of implementations + +It should be activated on Puppetservers that have the environments and modules available to import data from. This works independently of the Puppet CA functionality. To use the Puppet run functionality, it also needs to configured via an implementation listed in the section below. + +To enable this module, make sure these lines are present in `/etc/foreman-proxy/settings.d/puppet.yml`: + +```yaml +:enabled: https +``` + +#### Puppet class/environment imports + +
Parsing manifests is done by Puppet itself, which means the manifests must be valid and pass syntax checks, else they won't show up. Use puppet parser validate example.pp to validate the content of a manifest.
+ +To get a list of environments, classes and their parameters, the proxy queries the Puppetserver on its own API. The URL and settings used for the proxy to Puppetserver API query can be controlled with the following settings in `/etc/foreman-proxy/settings.d/puppet_proxy_puppet_api.yml`: + +```yaml +# URL of the Puppet server itself for API requests +#:puppet_url: https://puppet.example.com:8140 +# +# SSL certificates used to access the puppet API +#:puppet_ssl_ca: /etc/puppetlabs/puppet/ssl/certs/ca.pem +#:puppet_ssl_cert: /etc/puppetlabs/puppet/ssl/certs/puppet.example.com.pem +#:puppet_ssl_key: /etc/puppetlabs/puppet/ssl/private_keys/puppet.example.com.pem +# +# Smart Proxy api timeout when Puppet's environment classes api is used and classes cache is disabled +#:api_timeout: 30 +``` + +The Puppetserver has to permit these API queries. The [HOCON-formatted auth.conf style](https://docs.puppet.com/puppetserver/latest/config_file_auth.html) is at /etc/puppetlabs/puppetserver/conf.d/auth.conf and requires these rules: + +```hocon +{ + match-request: { + path: "/puppet/v3/environments" + type: path + method: get + } + allow: "*" + sort-order: 500 + name: "puppetlabs environments" +}, +{ + match-request: { + path: "/puppet/v3/environment_classes" + type: path + method: get + } + allow: "*" + sort-order: 500 + name: "puppetlabs environment classes" +}, +``` diff --git a/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md b/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md new file mode 100644 index 0000000000..9f8b4400d0 --- /dev/null +++ b/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md @@ -0,0 +1,121 @@ + +Activate the Puppet CA management module within the Smart Proxy instance. This is used to manage the autosign configuration and handle listing, signing and revocation of individual certificates. + +Builtin providers are: + +* `puppetca_hostname_whitelisting` - direct management of Puppet's `autosign.conf` +* `puppetca_token_whitelisting` - manage token-based signing of certificate requests + +This should only be enabled in the Smart Proxy that is hosted on the machine responsible for providing certificates to your puppet clients. On this host enable the feature in `puppetca.yml`: + +```yaml +:enabled: https +``` + +Also choose the provider to use, default should be `puppetca_hostname_whitelisting`: +```yaml +:use_provider: puppetca_hostname_whitelisting +``` + +Lastly the Puppet version needs to be specified. Since version 6 the `puppetca_http_api` implementation is used while on earlier versions the `puppetca_puppet_cert` implementation is used. +```yaml +:puppet_version: '6.8.0' +``` + +#### puppetca_hostname_whitelisting + +The `puppetca_hostname_whitelisting` provider directly manages Puppet's `autosign.conf` file. +This will create an autosign entry for a host during deployment and remove it when deployment is finished. +Furthermore it allows you to manage entries manually using the Foreman WebUI. + +The **autosignfile** setting in `puppetca_hostname_whitelisting.yml` is used to find autosign.conf: + +```yaml +:autosignfile: /etc/puppetlabs/puppet/autosign.conf +``` + +The location of the file can be determined with `puppet config print autosign`. + +The proxy requires write access to the puppet autosign.conf file, which is usually owner and group puppet, and has mode 0644 according to the puppet defaults. Ensure the foreman-proxy user is added to the puppet group ( e.g. `gpasswd -a foreman-proxy puppet` or `usermod -aG puppet foreman-proxy`) + +puppet.conf: +```ini +[master] +autosign = $confdir/autosign.conf {owner = service, group = service, mode = 664 } +``` + +#### puppetca_token_whitelisting + +The `puppetca_token_whitelisting` provider uses a token-based certificate signing managed by the Smart Proxy itself and queried by Puppet during Provisioning. +This provider adds more security and logging to the autosigning process but does not allow for manual creation of autosigning entries. + +This provider has the following settings in `puppetca_token_whitelisting.yml`: + +```yaml +:sign_all: false +:token_ttl: 360 +:tokens_file: /var/lib/foreman-proxy/tokens.yml +``` + +By changing **sign_all** to `true` you will disable token verification and sign all certificate requests. +The setting **token_ttl** defines how long a token after creation is valid in minutes. +**tokens_file** sets the path to the file used to store tokens during deployment, the foreman-proxy user requires read and write access to this file. + +You can also change the certificate used for encrypting the token file by setting **certificate**. By default it uses the certificate of the Smart Proxy defined in `settings.yml` as **ssl_certificate**. + +To integrate this in Puppet the script `puppet_sign.rb` provided by the Smart Proxy has to be used for verfication of the tokens during certificate signing. +If installed via package the script should be already located at `/usr/libexec/foreman-proxy/puppet_sign.rb`. +For manual installation the script can be found on [Github](https://github.com/theforeman/smart-proxy/blob/develop/extra/puppet_sign.rb). Using the latest version should be fine, if you encounter problems try the one released with your Smart Proxy version. +The script has to be executable by the same user running the Puppet server, typically puppet. + +After deploying the script the Puppet configuration has to be changed to point the **autosign** setting to the script. + +```ini +[master] +autosign = /usr/libexec/foreman-proxy/puppet_sign.rb +``` + +#### puppetca_puppet_cert + +**Note** this is used in Puppet 5 and earlier as determined by the `puppet_version` setting in `puppetca.yml`. + +This implementation is used for managing certificates. It uses the `puppet cert` command and typically requires sudo access for the proxy. + +```yaml +:ssldir: /etc/puppetlabs/puppet/ssl +#:puppetca_use_sudo: false +#:sudo_command: /usr/bin/sudo +``` + +The `ssldir` setting is required and can be determined with `puppet config print ssldir`. Puppet AIO defaults to using `/etc/puppetlabs/puppet/ssl`. + +By default sudo is used but can be disabled with `puppetca_use_sudo` setting. The sudo command is dermined via the `PATH` variable or can be explicitly set with the `sudo_command` setting. + +For sudo to work correctly, it must be configured to allow `puppet cert` with NOPASSWD and without requiretty. Under a Puppet AIO installation, configuration should be: + +``` +foreman-proxy ALL = NOPASSWD: /opt/puppetlabs/bin/puppet cert * +Defaults:foreman-proxy !requiretty +``` + +Under a non-AIO Puppet installation: + +``` +foreman-proxy ALL = NOPASSWD: /usr/bin/puppet cert * +Defaults:foreman-proxy !requiretty +``` + +#### puppetca_http_api + +**Note** this is used in Puppet 6 and newer as determined by the `puppet_version` setting in `puppetca.yml`. + +As the name implies, Puppetserver's HTTP API is used to manage certificates. In its configuration file `puppetca_http_api.yml` the connection details are configured: + +```yaml +:puppet_url: https://puppet.example.com:8140 +:puppet_ssl_ca: /etc/puppetlabs/ssl/certs/ca.pem +:puppet_ssl_cert: /etc/puppetlabs/ssl/certs/puppet.example.com.pem +:puppet_ssl_key: /etc/puppetlabs/ssl/private_keys/puppet.example.com.pem +``` + +The Puppet server does not need to be on the same host, but only the `puppetca_token_whitelisting` provider supports this. Note the Puppetserver also needs to allow access to the Smart Proxy. diff --git a/_includes/manuals/3.12/4.3.8.2_freeipa_realm.md b/_includes/manuals/3.12/4.3.8.2_freeipa_realm.md new file mode 100644 index 0000000000..10d1be29ff --- /dev/null +++ b/_includes/manuals/3.12/4.3.8.2_freeipa_realm.md @@ -0,0 +1,87 @@ +The FreeIPA implementation of the realm proxy is able to add a host entry to FreeIPA, send the hostgroup name, and request a one-time registration password. + +##### Configuration of FreeIPA + +In order to create the realm user and keytab to authenticate to FreeIPA, you can use the included `foreman-prepare-realm` tool. Your Smart Proxy must be registered to the FreeIPA realm already, and have the ipa-admintools package installed. + +Simply provide a user with admin rights in FreeIPA, and a target user to create. + +
+Do not use 'foreman-proxy' as the username for this -- this is a local user used for running the Smart Proxy service. +
+ + # foreman-prepare-realm admin realm-proxy + Password for admin@EXAMPLE.COM: + --------------------------------------- + Added permission "modify host password" + --------------------------------------- + Permission name: modify host password + Permissions: write + Attributes: userpassword + Type: host + [...] + Keytab successfully retrieved and stored in: freeipa.keytab + Realm Proxy User: realm-proxy + Realm Proxy Keytab: /root/freeipa.keytab + +##### Configuration of Smart Proxy + +Copy the freeipa.keytab created above to /etc/foreman-proxy/freeipa.keytab and set +the correct permissions: + + chown foreman-proxy /etc/foreman-proxy/freeipa.keytab + chmod 600 /etc/foreman-proxy/freeipa.keytab + +Then update `settings.d/realm_freeipa.yml` with the relevant settings. + +If you're using FreeIPA to manage DNS records, and want them to be automatically deleted when the host is deleted in Foreman, set this to true: + +```yaml +:remove_dns: true +``` + +Finally, trust the IPA Certificate Authority. Ensure you have the most up-to-date version of the `ca-certificates` package installed. + + cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt + update-ca-trust enable + update-ca-trust + +You will need to disable the DNS proxy for hosts that are provisioned with a realm set, as FreeIPA adds the forward record for you. In order to support adding a reverse lookup record also, you will need to go into the settings for the forward lookup zone on the IPA server and tick `Allow PTR sync`. This will make sure that FreeIPA creates the PTR records for you. + +##### Using Automember Rules + +FreeIPA supports the ability to setup automember rules based on attributes of a system. When using the FreeIPA proxy, the Foreman host group is available as a parameter in FreeIPA known as `userclass`. Nested host groups are sent as displayed in the Foreman UI, e.g. "Parent/Child/Child". Note that Foreman does send updates to FreeIPA, however automember rules are only applied at initial add. This will be coming in a [future version of FreeIPA](https://fedorahosted.org/freeipa/ticket/3752). + +First, we create a host group in FreeIPA: + + # ipa hostgroup-add webservers + Description: web servers + ---------------------------- + Added hostgroup "webservers" + ---------------------------- + Host-group: webservers + Description: web servers + +Define an automember rule: + + # ipa automember-add --type=hostgroup webservers + ---------------------------------- + Added automember rule "webservers" + ---------------------------------- + Automember Rule: webservers + +Create an automember condition based on the `userclass` attribute: + + # ipa automember-add-condition --key=userclass --type=hostgroup --inclusive-regex=^webserver webservers + ---------------------------------- + Added condition(s) to "webservers" + ---------------------------------- + Automember Rule: webservers + Inclusive Regex: userclass=^webserver + ---------------------------- + Number of conditions added 1 + ---------------------------- + +When a machine in Foreman is in the "webservers" host group, it will automatically be added to the FreeIPA +"webservers" host group as well. FreeIPA host groups allow for Host-based access controls (HBAC), sudo policies, +etc. diff --git a/_includes/manuals/3.12/4.3.8_smartproxy_realm.md b/_includes/manuals/3.12/4.3.8_smartproxy_realm.md new file mode 100644 index 0000000000..ac07bf825e --- /dev/null +++ b/_includes/manuals/3.12/4.3.8_smartproxy_realm.md @@ -0,0 +1,21 @@ + +Activate the realm management module within the Smart Proxy instance. This manages Kerberos realms or domains, allowing Foreman to add and remove hosts to enable them to join the realm/domain automatically during provisioning. + +```yaml +:enabled: https +:use_provider: realm_freeipa +``` + +Builtin providers are: + +* `realm_freeipa` - host object management in FreeIPA + +The configuration for each provider should be in its respective file, i.e: `/etc/foreman-proxy/settings.d/realm_freeipa.yml`. + +The following settings control authentication of the proxy to the realm for management of hosts. +In `realm_freeipa.yml`: +```yaml +# Authentication for Kerberos-based Realms +:keytab_path: /etc/foreman-proxy/freeipa.keytab +:principal: realm-proxy@EXAMPLE.COM +``` diff --git a/_includes/manuals/3.12/4.3.9_smartproxy_tftp.md b/_includes/manuals/3.12/4.3.9_smartproxy_tftp.md new file mode 100644 index 0000000000..78a1b0f3d5 --- /dev/null +++ b/_includes/manuals/3.12/4.3.9_smartproxy_tftp.md @@ -0,0 +1,81 @@ + +#### tftp.yml + +Activate the TFTP management module within the Smart Proxy instance. This is designed to manage files on a TFTP server, e.g. bootloaders for OS installation and PXE menu files. + +The *tftproot* value is directory into which TFTP files are copied and then served from. The TFTP daemon will also be expected to chroot to this location. This component is only supported in a Unix environment. +```yaml +:enabled: https +:tftproot: /var/lib/tftpboot +:tftp_servername: name of your tftp server (used for next server value in your dhcp reservation) - defaults to the host name of your proxy. +``` + +
The foreman-proxy user must have read/write access to the _tftpboot/pxelinux.cfg_ and _tftpboot/boot_ directories.
+ +#### Unattended installation + +An essential first step in netbooting a system is preparing the TFTP server with the PXE configuration file and boot images. This document assumes that you have already configured your DHCP infrastructure, either via manual configuration or through the DHCP smart proxy. + +##### Setting Up the Proxy Server Host + +Regardless of the filesystem setup is performed, you must also make sure you have the wget utility installed and in the default path. *wget* is used to download OS specific installation when a given host is enabled for the build process. + +##### Automatic Setup + +Foreman includes a [TFTP server module](https://github.com/theforeman/puppet-foreman_proxy/blob/master/manifests/tftp.pp) that will perform all of the basic setup. It defaults to TFTP root of */var/lib/tftpboot*, which may change if necessary. You will still need to provide the basic TFTP load images in your TFTP root directory. For vanilla PXE booting via PXELinux, this includes *pxelinux.0*, *menu.c32*, and *chain.c32*, for PXEGrub this includes *grub2/* and *grub/* subdirectories. + +##### Manual Setup + +The setup is very simple, and may be performed manually if desired. + +1. The TFTP root directory must exist (we will use */var/lib/tftpboot* in this example). +2. Populate */var/lib/tftpboot* with PXE booting prerequisites. These can be taken from syslinux (usually in /usr/share/syslinux on RHEL) . At a minimum, this should include: + * *pxelinux.0* + * *menu.c32* + * *chain.c32* + * *ldlinux.c32* if syslinux provides it +3. Populate the following prerequisites when PXE Grub bootloader is planned. These files can be found in OS distribution repositories, DVD/CD or packages (e.g. *grub2-efi* on Red Hats which installs into */boot/EFI*). Alternatively, these files can be built from modules using *grub2-mkimage* or *grub-mkimage* and signed for SecureBoot support. + * */var/lib/tftpboot/grub2* with *grubx64.efi* or *grubia32.efi* + * */var/lib/tftpboot/grub* with *bootx64.efi* or *bootia32.efi* +4. Create the directory */var/lib/tftpboot/boot* and make it writeable by the foreman proxy user (foreman-proxy, for instance, when installing through a rpm package). +5. Create the directory */var/lib/tftpboot/pxelinux.cfg* and make it writeable by the foreman proxy user (foreman-proxy). +6. Make sure */var/lib/tftpboot/grub* and */var/lib/tftpboot/grub2* are both writeable by the foreman proxy user (foreman-proxy). +7. Verify SELinux labels when using SELinux. + +* Note: if CentOS 7 is used, please make sure to edit the URL under Hosts -> Provisioning Setup -> Installation Media, to to exclude the $minor version. For example: http://mirror.centos.org/centos/$major/os/$arch + +##### Setting Up Foreman + +In most cases, the default templates should work fine. You do, however, need to make sure that a PXELinux or iPXE template is associated with your hosts. See [Using PXE to Provision Hosts](https://docs.theforeman.org/{{ page.version }}/Provisioning_Hosts/index-foreman-el.html#Using_PXE_to_Provision_Hosts_provisioning) for details. The template will be used to define the PXE configuration file when a host is enabled for build. + +##### Workflow + +This is a rough outline of the steps triggered on the TFTP smart proxy host when you click on the "Build" link for a host. + +1. Call *mkdir -p /var/lib/tftpboot/pxelinux.cfg* if it does not already exist. +2. Create a host-specific TFTP configuration file in */var/lib/tftpboot/pxelinux.cfg/01-XX-XX-XX-XX-XX-XX*, named based off of the MAC address, using the associated PXE template. +3. Call *mkdir -p /var/lib/tftpboot/boot* if it does not already exist. +4. Download the OS specific kernel and initrd files using wget. + 1. The download URLs are derived from the installation media path, and OS specific log (see *app/models/redhat.rb* and *debian.rb* in foreman for examples of the gory details). + 2. The *debian.rb* file tries to guess if you want Ubuntu or Debian, based on the Name you give to your OS in the UI. If the name does not contain 'ubuntu' or 'debian', it may default to debian, hence fail to fetch the kernel/initrd. + 3. cd into /var/lib/tftpboot/boot and check that the filesizes are not zero. Check /var/log/foreman-proxy/proxy.log for possible errors. +5. The exact wget command is `wget --no-check-certificate -nv -c -O ""` +6. At this point, the TFTP state is ready for the installation process. +7. Once the host has completed installation, the OS specific installation script should inform foreman by retrieving the built URL. +8. The host-specific TFTP configuration file is deleted. +9. The kernel and initrd are not deleted, but left in place for future installs of the same OS and architecture combination. Please note that in the unlikely case that these files are modified, the simplistic freshness check of wget will likely get confused, corrupting the downloaded versions of the files. If this happens, you should simply delete the files and let them be re-downloaded from scratch. + +**To make sure that you trigger the above workflow make sure you've satisfied these requirements:** + +1. at least 1 host is put in build mode +2. the host is using a subnet with a TFTP proxy + +##### Limitations + +At the moment, the proxy is not able to fetch boot files using NFS. +As a workaround, expose your installation medium (or use a public mirror) over http/ftp to configure one machine with the require boot files. +this would be resolved as part of #992. + +#### Global default templates + +You can build PXE default on TFTP proxy from Foreman UI from 'Provisioning Templates' page using 'Build PXE Default' button. You also have the ability to choose which templates are used for this action. Foreman exposes the following settings in the 'Provisioning' group for this purpose: Global default PXEGrub template, Global default PXEGrub2 template and Global default PXELinux template. When settings are empty, Foreman uses default values: PXELinux global default, PXEGrub global default and PXEGrub2 global default. diff --git a/_includes/manuals/3.12/4.3_smartproxy.md b/_includes/manuals/3.12/4.3_smartproxy.md new file mode 100644 index 0000000000..f92cf12b79 --- /dev/null +++ b/_includes/manuals/3.12/4.3_smartproxy.md @@ -0,0 +1,25 @@ + +The Smart Proxy is a project which provides a restful API to various sub-systems. + +Its goal is to provide an API for a higher level orchestration tools (such as Foreman). +The Smart proxy provides an easy way to add or extended existing subsystems and APIs using plugins. + +Currently supported (Click on the links below for more details). + +* [**DHCP**](manuals/{{page.version}}/index.html#4.3.4DHCP) - ISC DHCP and MS DHCP Servers +* [**DNS**](manuals/{{page.version}}/index.html#4.3.5DNS) - Bind and MS DNS Servers +* [**Puppet**](manuals/{{page.version}}/index.html#4.3.6Puppet) - Puppet server version 5 or 6 +* [**Puppet CA**](manuals/{{page.version}}/index.html#4.3.7PuppetCA) - Manage certificate signing, cleaning and autosign on a Puppet CA server +* [**Realm**](manuals/{{page.version}}/index.html#4.3.8Realm) - Manage host registration to a realm (e.g. FreeIPA) +* [**Templates**](manuals/{{page.version}}/index.html#4.3.12Templates) - Proxy template requests from hosts in isolated networks +* [**TFTP**](manuals/{{page.version}}/index.html#4.3.9TFTP) - Any UNIX based tftp server + +If you require another sub system type or implementation, please add a new feature request or consider writing a plugin. + +Once your smart proxy is running, each of the relevant sub systems needs to be configured via the [settings.d/*](manuals/{{page.version}}/index.html#4.3.2SmartProxySettings) files in the config directory. + + + + + + diff --git a/_includes/manuals/3.12/4.4.1_prov_os.md b/_includes/manuals/3.12/4.4.1_prov_os.md new file mode 100644 index 0000000000..fa8d6304ef --- /dev/null +++ b/_includes/manuals/3.12/4.4.1_prov_os.md @@ -0,0 +1,14 @@ + +The Operating Systems page (*Hosts -> Provisioning Setup -> Operating Systems*) details the OSs known to Foreman, and is the central point that the other required components tie into. + +#### Creating an Operating System + +Simply click *Create Operating System* on the main page. You will be taken to a screen where you can create the bare essentials of a new OS. Not everything required for a successful provision is on this page (yet) - the remaining components will appear for selection as we create them. + +You will need to fill in the first few parts of the form (Name, Major, Minor, Family, and possibly some family-dependent information). In the case of OSs like Fedora, it is fine to leave Minor blank. + +If the default Partition Tables & Installation media are suitable, then you can assign them now. If not, return here after each step in this chapter to assign the newly created objects to your Operating System + +#### Auto-created Operating Systems + +Foreman does not come with any Operating Systems by default. However, Foreman will detect the Operating System of any host which reports in via Puppet - if the OS of that Host is supported, it will be created (with very basic settings) and assigned to the Host. Thus you may find some OSs already created for you. diff --git a/_includes/manuals/3.12/4.4.2_prov_media.md b/_includes/manuals/3.12/4.4.2_prov_media.md new file mode 100644 index 0000000000..70ce404005 --- /dev/null +++ b/_includes/manuals/3.12/4.4.2_prov_media.md @@ -0,0 +1,14 @@ + +The Installation Media represents the web URL from where the installation packages can be retrieved (i.e. the OS mirror). Some OS Media is pre-created for you when Foreman is first installed. However, it is best to edit the media you are going to use and ensure the Family is set. + +#### New Installation Media + +If your OS of choice does not have a mirror pre-created for you, click the *New Medium* button to create one. There are a few variables which can be used to pad out the URL. For example: + + http://mirror.averse.net/centos/$major.$minor/os/$arch + +Be sure to set the Family for the Media + +#### Assign to Operating System + +If you have not already done so, return to the Operating System page for your OS and assign the Media to it now. diff --git a/_includes/manuals/3.12/4.4.3_prov_templates.md b/_includes/manuals/3.12/4.4.3_prov_templates.md new file mode 100644 index 0000000000..781b9713c4 --- /dev/null +++ b/_includes/manuals/3.12/4.4.3_prov_templates.md @@ -0,0 +1,103 @@ + +Provisioning Templates are the core of Foreman's flexibility to deploy the right code or options to the right OS. There are several types of template, along with a flexible matching system to deliver different templates to different Hosts. + +Foreman comes with pre-created templates for the more common OSs, but you will need to review these. All these templates are locked by default, hence they can not be modified. Most of them are customizable through parameters, but if you need some custom functionality, the recommended workflow is to clone the template and edit the clone. You can unlock the pre-created template and edit it directly, but note that any custom change will be overridden on any Foreman update. If you believe your change is worthy of inclusion in next Foreman release, please consider sending a patch to [foreman repository's templates](https://github.com/theforeman/foreman/tree/develop/app/views/unattended) via the normal [contribution process](https://www.theforeman.org/contribute.html). + +#### Template Kinds + +There are several template kinds: + +* PXELinux, PXEGrub, PXEGrub2 - Deployed to the TFTP server to ensure the Host boots the correct installer with the correct kernel options (also referred to as PXE templates) +* Provision - The main unattended installation file; e.g. Kickstart or Preseed +* Finish - A post-install script used to take custom actions after the main provisioning is complete +* user_data - Similar to a Finish script, this can be assigned to hosts built on user_data-capable images (e.g. Openstack, EC2, etc) +* Script - An arbitrary script, not used by default, useful for certain custom tasks +* iPXE - Used in {g,i}PXE environments in place of PXELinux (do not confuse with PXE templates above) + +In practice, most environments only make use of the first 3. The *Create Host* action deploys the PXELinux template to the TFTP server. The PXELinux template directs the host to retrieve the Provision template. The Provision template will direct the installer to retrieve and run the Finish template at the end of the install, and the Finish template will notify Foreman the build is complete just before reboot. + +##### Editing Templates + +Unlocked templates can be edited from the *Hosts > Provisioning templates* menu, or from an existing host page under its *Templates* tab (which shows the templates in use). + +The templates use the ERB (Embedded Ruby) templating language, allowing data from the host in Foreman to be added to the template output and for conditional content. The default templates make heavy use of the ERB feature, adding and changing the template behavior based on parameters, the operating system, or the networking configuration assigned to the host. + +There are two general types of ERB syntax in templates. The `<%=` prefix outputs the value of the following expression into the rendered template, e.g. to output the hostname: + + <%= @host.name %> + +The `<%` prefix without the equals sign (`=`) is a general code block that may contain conditionals, variable assignments, or loops which are not output when rendered. Comments may also be in these blocks, prefixed with `#`. + + <% + a_variable = @host.name + %> + <%= a_variable %> + +Other examples of ERB syntax are given on the *Help* tab of the template editor, and many more examples are available on the [Template Writing Reference](https://docs.theforeman.org/{{ page.version }}/Managing_Hosts/index-foreman-el.html#Template_Writing_Reference_managing-hosts). The *Help* tab also lists available *Global methods (functions)* provided by Foreman such as `foreman_url` (the URL for unattended calls to Foreman), and `template_name`. + +The methods available on the provided `@host` variable are limited by default (when `safemode_render` is enabled) to prevent exploitation of Foreman through templates. The permitted methods on all types of objects can be found in the *Safe mode methods and variables* table under the *Help* tab. + +As noted in section [4.1.4 Auditing](manuals/{{page.version}}/index.html#4.1.4Auditing), changes to the templates are logged as diffs - you can browse the history of changes to the templates from the *History* tab within the *Edit Template* page. You can also revert changes here. + +#### Template Association + +When editing a Template, you must assign a list of Operating Systems which this Template can be used with. Optionally, you can restrict a template to a list of Hostgroups and/or Environments + +When a Host requests a template (e.g. during provisioning), Foreman will select the best match from the available templates of that type, in the following order: + +* Host-group and Environment +* Host-group only +* Environment only +* Operating system default + +The final entry, Operating System default, can be set by editing the Operating System page. + +##### Associating an Operating System default template + +You will need to associate at least one PXE, Provision, and Finish template to your Operating System, and this must be done in two steps. First edit each of the templates, switch to the Association tab, and ensure the appropriate OSs are checked. Then edit the Operating System, switch to the Templates tab, and choose a default template for each template kind. + +More than one PXE template can be associated. In this case, all associated PXE templates are deployed to the TFTP server and only one is picked up during provisioning according to the _PXE Loader_ setting (see below). + +##### Templates Details +For image based installs there are two methods to customize and finish the installation. *Finish templates* and *User Data templates*: + +###### Finish Templates +Finish templates are available for all hypervisors that support image based installs where the foreman server can reach the newly installed machine via ssh and scp. The script generated from the finish template is copied by the Foreman to the newly installed system via scp using username and password specified with the image. It is then executed by connecting again via ssh, making the script executable and either executing it directly or via sudo if the specified user is not root. Standard output and standard error are logged to a file in the same directory named *bootstrap-UUID.log*. + +###### User Data Templates +User Data Templates are available for hypervisors that support customization via tools like *cloud-init*. In this case the installed machine does not need be reachable via ssh by the Foreman server. However, the installed must be able to reach Foreman or a Smart Proxy with the templates feature via http(s) to notify the setup has finished. + +###### PXE Loader + +When creating a new Host, the _PXE Loader_ option must be selected in order to pass +the correct DHCP filename option to the client. One option out of the following +must be chosen: + +* PXELinux BIOS (loads `pxelinux.0` filename from TFTP) +* PXELinux UEFI (loads `pxelinux.efi` filename from TFTP) +* PXEGrub UEFI (loads `grub/bootx64.efi` filename from TFTP) +* PXEGrub UEFI SecureBoot (loads `grub/shim.efi` filename from TFTP) +* PXEGrub2 UEFI (loads `grub2/grubx64.efi` filename from TFTP) +* PXEGrub2 UEFI SecureBoot (loads `grub2/shim.efi` filename from TFTP) +* None - no filename passed (e.g. for HTTP booting via iPXE) + +Grub filenames are different for each individual architecture associated with +the Host: + +* `grub/bootia32.efi` (for Intel named \"i\*86\" where \* can be any character) +* `grub/bootx64.efi` (for Intel named \"x86-64\") +* `grub2/grubia32.efi` (for Intel named \"i\*86\" where \* can be any character) +* `grub2/grubx64.efi` (for Intel named \"x86-64\") +* `grub2/grubaa64.efi` (for ARM 64 named either \"aa64\" or \"aarch64\") +* `grub2/grubppc64.efi` (for IBM POWER named \"ppc64") +* `grub2/grubppc64le.efi` (for IBM POWER Little Endian named \"ppc64le\") +* `grub2/grubXYZ.efi` (for arbitrary Architecture named \"XYZ\") + +Foreman installer only installs `pxelinux.0` and `grub2/grubx64.efi` (if grub2 +is available). In order to boot systems via other loaders like PXELinux EFI or +Grub 1 (legacy), deploy the required bootloader files in the TFTP directory. + +Some operating systems use a "shim" loader for SecureBoot (e.g. Red Hat +Enterprise Linux and clones). To use SecureBoot with an operating system that +does not use a shim chainloader, make a copy of the signed EFI loader named +`shim.efi` or make a symlink in order to do secure boot. diff --git a/_includes/manuals/3.12/4.4.4_prov_archs.md b/_includes/manuals/3.12/4.4.4_prov_archs.md new file mode 100644 index 0000000000..0e0f4fa5af --- /dev/null +++ b/_includes/manuals/3.12/4.4.4_prov_archs.md @@ -0,0 +1,6 @@ + +Architectures are simple objects, usually created by Foreman automatically when Hosts check in via Puppet. However, none are created by default, so you may need to create them if you're not using Foreman for reporting. + +#### Creating a new Architecture + +Simply click *New Architecture* to create a new one. This should match the Facter fact *:architecture* e.g. "x86_64". If you've already created some Operating Systems, you can associate the Architecture with the OS now; if not, the list of Architectures will be present when you create an OS. diff --git a/_includes/manuals/3.12/4.4.4_prov_ptables.md b/_includes/manuals/3.12/4.4.4_prov_ptables.md new file mode 100644 index 0000000000..c925e5f56b --- /dev/null +++ b/_includes/manuals/3.12/4.4.4_prov_ptables.md @@ -0,0 +1,170 @@ + +Partition templates are a subset of normal Provisioning Templates. They are handled separately because it is frequently the case that an admin wants to deploy the same host template (packages, services, etc) with just a different harddisk layout to account for different servers' capabilities. + +Foreman comes with pre-created templates for common Operating Systems, but it is good to edit the template, check it's content and it's Family setting. If the Family is wrong, be sure to go back to Operating Systems and associate it with your Operating System. + +#### Per-Host Partition tables + +When creating a new Host, you will be given the option to create an individual partition table. This is essentially a 'one-off' partition table that is stored with the host and used only for that host. It replaces the choice of Partition Table from the normal list of those associated with the selected OS. + +#### Dynamic Partition tables +Some operating systems allow you to create partition tables via scripts. At the moment Kickstart and AutoYaST based systems can use this feature. Partition templates starting with `#Dynamic` are interpreted as scripts rather than static partition tables. The Provisioning Template needs to support this feature (search for `@dynamic`). This enables you to make choices on the fly during provisioning (or re-provisioning). + +##### Kickstart Dynamic Partition tables +Kickstart will run dynamic partition tables as a pre-install bash script using a %pre scriplet. This script needs to create a complete Kickstart partition table in '/tmp/diskpart.cfg'. This partition table will then be read by anaconda for the installation by using `%include /tmp/diskpart.cfg`. + +Example Dynamic Partition table: + +``` +#Dynamic - this line tells Foreman this is a script rather then a static layout +#This snippets define the swap partition size, it would generate a partition twice the size of the memory if your physical memory is up to 2GB +#or will create a swap partition with your memory size + 2GB. + +#get the actual memory installed on the system and divide by 1024 to get it in MB +act_mem=$((`grep MemTotal: /proc/meminfo | sed 's/^MemTotal: *//'|sed 's/ .*//'` / 1024)) + +#check if the memory is less than 2GB then swap is double the memory else it is memory plus 2 GB +if [ "$act_mem" -gt 2048 ]; then + vir_mem=$(($act_mem + 2048)) +else + vir_mem=$(($act_mem * 2)) +fi + +#copy all the HDD partitions to the temp file for execution +cat < /tmp/diskpart.cfg +zerombr yes +clearpart --all --initlabel +part swap --size "$vir_mem" +part /boot --fstype ext3 --size 100 --asprimary +part / --fstype ext3 --size 1024 --grow +EOF +``` + +##### AutoYaST Dynamic Partition tables +AutoYaST will run dynamic partition tables as a pre-install bash script. This script needs to create a AutoYaST XML file in `/tmp/profile/modified.xml`. The modified.xml file will be read by YaST after your script has finished. An example for getting the same functionality as with Kickstart would be to create your XML partition table in `/tmp/diskpart.cfg` and sed it together with the original AutoYaST XML like this: `sed '/<\/ntp-client>/ r /tmp/diskpart.cfg' /tmp/profile/autoinst.xml > /tmp/profile/modified.xml`. Inserting after ntp-client section is just a suggestion that uses the same style the community-templates do. The example uses a simplified version of the AutoYaST LVM Partition table template. + +Example Dynamic Partition table: + +``` +#Dynamic - this line tells Foreman this is a script rather then a static layout +#This snippets define the swap partition size, it would generate a partition twice the size of the memory if your physical memory is up to 2GB +#or will create a swap partition with your memory size + 2GB. + +#get the actual memory installed on the system and divide by 1024 to get it in MB +act_mem=$((`grep MemTotal: /proc/meminfo | sed 's/^MemTotal: *//'|sed 's/ .*//'` / 1024)) + +#check if the memory is less than 2GB then swap is double the memory else it is memory plus 2 GB +if [ "$act_mem" -gt 2048 ]; then + vir_mem=$(($act_mem + 2048)) +else + vir_mem=$(($act_mem * 2)) +fi + +#copy all the HDD partitions to the temp file for execution +cat < /tmp/diskpart.cfg + + + /dev/sda + true + + + true + ext3 + true + /boot + 131 + 1 + 1G + 1 + 4 + + + + true + false + vg00 + 142 + 2 + max + + + + CT_DISK + all + + + /dev/vg00 + true + + + true + ext3 + true + root + / + 10G + + + true + swap + true + swap + swap + ${vir_mem}M + + + CT_LVM + all + + +EOF +sed '/<\/ntp-client>/ r /tmp/diskpart.cfg' /tmp/profile/autoinst.xml > /tmp/profile/modified.xml +``` +##### Configuration + +A partition table entry represents either +* An explicit layout for the partitions of your hard drive(s). E.G. +``` +zerombr +clearpart --all --initlabel +part /boot --fstype ext3 --size=100 --asprimary +part / --fstype ext3 --size=1024 --grow +part swap --recommended +``` +* A script to dynamically calculate the desired sizes. E.G. + +``` +#Dynamic - The below code is to manage the swap size + +#get the actual memory installed on the system and divide by 1024 to get it in MB +usable_ram=$((`awk '$1 ~ /^MemTotal/ {printf "%d\n", $2 / 1024}' /proc/meminfo`)) + +#check if the memory is less than 2GB then swap is double the memory else it is maximum 24 G for really inactive stuff. +if [ "$usable_ram" -le 2048 ]; then + swap_size=$(($usable_ram * 2)) +else + swap_size=$(($usable_ram + 2048)) +fi +if [ $swap_size -gt 24576 ] ; then + swap_size=24576 +fi + +#copy all the HDD partitions to the temp file for execution +cat << EOF > /tmp/diskpart.cfg +zerombr +clearpart --all --initlabel +part swap --size 250 --maxsize "$swap_size" --grow +part /boot --fstype ext3 --size 100 --asprimary +part / --fstype ext3 --size 8192 --maxsize 12288 --grow +part /tmp2 --size 250 --fstype ext3 --grow +EOF +``` +The inclusion of the keyword string `#Dynamic` at the start of a line lets Foreman know that this is not an explicit +disk layout and must treated as a shell script, executed prior to the install process and that the explicit partition +table will be found at `/tmp/diskpart.cfg` during the build process. + +The dynamic partitioning style is currently only available for the Red Hat family of operating systems, +all others must provide an explicit list of partitions and sizes. + +You may also associate one or more operating systems with this partition table or alternatively set this up later on +the Operating systems page. diff --git a/_includes/manuals/3.12/4.4.6_prov_workflow.md b/_includes/manuals/3.12/4.4.6_prov_workflow.md new file mode 100644 index 0000000000..13bb83a019 --- /dev/null +++ b/_includes/manuals/3.12/4.4.6_prov_workflow.md @@ -0,0 +1,73 @@ + +Foreman performs a number of orchestration steps when performing unattended installation or provisioning, which vary depending on the integration options chosen - e.g. use of [compute resources](/manuals/{{page.version}}/index.html#5.2ComputeResources), configuration management tool and provisioning method (network/PXE/image). + +#### 4.4.6.1 Example: PXE booting an instance with Salt configuration + +The following example uses: + +* Compute resource (oVirt), also applicable to Libvirt and VMware +* Network (PXE) provisioning with DHCP and TFTP orchestration +* DNS orchestration +* Salt configuration management, also applicable to Puppet + +![Example A workflow diagram](/static/images/diagrams/foreman_workflow_final.jpg) + +##### Steps + +1. On the New Host page, the default VM configuration is shown and compute profiles can be applied. +2. An unused IP address is requested from the DHCP smart proxy associated with the subnet. +3. The IP address field is filled in on the New Host page. +4. n/a +5. The New Host page is submitted. +6. Foreman contacts the compute resource to create the virtual machine. +7. The compute resource creates a virtual machine on a hypervisor. +8. The VM's MAC address is returned from the compute resource and stored on the host. +9. A reservation is created on the DHCP smart proxy associated with the subnet. +10. DNS records are set up: + 1. A forward DNS record is created on the smart proxy associated with the domain. + 1. A reverse DNS record is created on the DNS smart proxy associated with the subnet. +11. A PXELinux menu is created for the host in the TFTP smart proxy associated with the subnet. +12. Foreman contacts the compute resource to power on the VM. +13. The compute resource powers up the virtual machine. +14. The host requests a DHCP lease from the DHCP server. +15. The DHCP lease response is returned with TFTP options (next-server, filename) set. +16. The host requests the bootloader and menu from the TFTP server. +17. The PXELinux menu and OS installer for the host is returned over TFTP. +18. The installer requests the "provision" template/script from Foreman. +19. Foreman renders the template and returns the resulting kickstart/preseed to the host. +20. Autosigning configuration for Salt (or Puppet) is added on the Salt or Puppet CA smart proxy. +21. The installer notifies Foreman of a successful build in the postinstall script. +22. The PXELinux menu is reverted to a "local boot" template. +23. The host requests its configuration from Salt or Puppet. +24. The host receives appropriate configuration using data defined in Foreman. +25. Configuration reports and facts are sent from Salt or Puppet to Foreman and stored. + +#### 4.4.6.2 Example: Cloud-based provisioning via cloud-init + +This example shows workflow of cloud-based provisioning on IaaS (e.g. +OpenStack) via cloud-init which configures Puppet agent to finish off the +configuration. + +![Cloud-based via cloud-init](/static/images/diagrams/cloud_init_workflow.png) + +#### 4.4.6.3 Example: Cloud-based provisioning via ssh + +This example shows workflow of cloud-based provisioning on IaaS (e.g. +OpenStack) via ssh finish template for Puppet agent configuration. + +![Cloud-based via ssh](/static/images/diagrams/cloud_ssh_workflow.png) + +#### 4.4.6.4 Example: Image-based provisioning via ssh + +This example shows workflow of image-based provisioning on virtualization +(e.g. oVirt, RHEV or VMware via ssh finish template for Puppet agent +configuration. + +![Image-based via ssh](/static/images/diagrams/image_workflow.png) + +#### 4.4.6.5 Example: Anaconda PXE-based provisioning + +This example shows workflow of PXE booting into Anaconda installer with +Puppet agent configuration. + +![Anaconda](/static/images/diagrams/pxe_workflow.png) diff --git a/_includes/manuals/3.12/4.4.7_prov_networking.md b/_includes/manuals/3.12/4.4.7_prov_networking.md new file mode 100644 index 0000000000..b699e271a2 --- /dev/null +++ b/_includes/manuals/3.12/4.4.7_prov_networking.md @@ -0,0 +1,39 @@ + +Foreman can store information about the networking setup of a host that it's provisioning, which can be used to configure the virtual machine, assign the correct IP addresses and network resources, then configure the OS correctly during the provisioning process. + +This section details the options available for network interfaces in the *New Host* form and how they're used. + +#### Host interface options + +* *Primary:* each host must have a single primary interface, which is used as the name of the host itself. This should be considered the main hostname and would usually also carry the default route. +* *Provision:* the interface on which provisioning of the operating system should be carried out. This will be used for PXE (if applicable) with TFTP menus, running SSH finish scripts etc. This may be different to the primary interface and should have access to Foreman and other provisioning systems. +* *Managed:* whether Foreman orchestrates creation of DNS entries, DHCP reservations and configuration of the interface during provisioning. Unmanaged interfaces would be used for informational purposes only. + +A simple, single-homed host would have one network interface with a DNS name set matching the hostname, then managed, primary and provision flags all ticked. This would create one interface with DNS and DHCP records (if configured) over which the OS would be set up. + +A dual or multi-homed host could have one interface with primary enabled ("host.example.com") and another network with provision enabled ("host-build.example.com"). If both are also managed, Foreman will create DNS and DHCP records for both, but on the provision interface, the next-server/filename options for PXE will also be set. A TFTP (PXELinux) menu would also be created for the provision interface's MAC address so the host can PXE boot on that physical interface, while its hostname would be assigned from the primary interface. + +#### Virtual machines and interfaces + +When Foreman deploys a host onto a compute resource, it creates a new interface on the VM for each interface specified when creating the host. + +After creation, Foreman reads back the network information and matches the created interfaces to the list of interfaces given for the host and stores the assigned MAC and IP addresses (depending on the compute resource type) in its database. It then continues with orchestration, creating DNS and DHCP records etc. for the addresses retrieved from the new VM. Once orchestration of these is complete, it powers up the VM. + +This design alleviates the need to supply MAC addresses for hosts being created on compute resources. + +#### Subnet options + +Subnets are defined in Foreman under *Infrastructure > Subnets*, and have a few options that affect how hosts are provisioned. + +* *IPAM:* DHCP will use a DHCP-enabled smart proxy, checking for assigned leases and reservations and suggesting a new IP from the range. Internal DB will use Foreman's list of already-assigned IPs and doesn't rely on a DHCP smart proxy. None disables auto-suggestion of IP addresses. +* *Boot mode:* during OS provisioning, the template will configure the interface with either a static IP address or to use DHCP depending on the value of this setting. + +Various combinations of the *IPAM* and *Boot mode* settings make sense, but the most common are *DHCP (IPAM)* with *DHCP (Boot mode)* and *Internal DB* with *Static*. + +#### Use within provisioning templates and Puppet + +Provisioning templates (such as kickstart, preseed or finish scripts) can make use of the interfaces data stored in Foreman for the host to configure the network. + +A snippet ("kickstart_networking_setup") is supplied by default in Foreman for kickstart-based OSes, which configures all managed network interfaces after the main OS installation is complete. This can be used in the %post kickstart section. No template is currently available for preseed-based OSes ([ticket](https://github.com/theforeman/community-templates/issues/173)) + +A hash of interfaces data is also made available to Puppet via a global ENC parameter called "foreman_interfaces". This can be used to fully configure the network from a Puppet run. diff --git a/_includes/manuals/3.12/4.4.8.1_prov_freebsd.md b/_includes/manuals/3.12/4.4.8.1_prov_freebsd.md new file mode 100644 index 0000000000..0a5922d2d1 --- /dev/null +++ b/_includes/manuals/3.12/4.4.8.1_prov_freebsd.md @@ -0,0 +1,23 @@ +As the FreeBSD installer itself does not support a kickstart-like pulling of a response file, a custom mfsBSD image with zfsinstall is used. Prebuilt images are available [for download](http://downloads.theforeman.org/FreeBSD/) to be placed into the boot directory of your TFTP server. + +However, these images can also be built from scratch as described below: + +##### Building an installer image + +This is an example how to build an image for FreeBSD 10.2-RELEASE. For other releases, simply replace the version accordingly. + + # fetch the necessary FreeBSD components + mkdir /tmp/basefiles + cd /tmp/basefiles + fetch ftp://ftp.freebsd.org/FreeBSD/releases/amd64/10.2-RELEASE/base.txz + fetch ftp://ftp.freebsd.org/FreeBSD/releases/amd64/10.2-RELEASE/kernel.txz + + # clone the git repository + git clone https://github.com/theforeman/mfsbsd.git + cd mfsbsd + + # build the image (you need to be root for this to succeed) + make BASE=/tmp/basefiles RELEASE=10.2-RELEASE ARCH=amd64 + + # copy the image into the TFTP server directory + cp mfsbsd-10.2-RELEASE-amd64.img /tftpboot/boot/FreeBSD-x86_64-10.2-mfs.img diff --git a/_includes/manuals/3.12/4.4.8.2_prov_sles.md b/_includes/manuals/3.12/4.4.8.2_prov_sles.md new file mode 100644 index 0000000000..bd8fd99c53 --- /dev/null +++ b/_includes/manuals/3.12/4.4.8.2_prov_sles.md @@ -0,0 +1,4 @@ +The installation media URL has to contain the contents of the first SLES DVD, it's easiest to loopback mount the ISO image on a webserver. For Puppet, the `systemsmanagement:puppet` repository on OBS is used. + +##### SLES 11 +For Puppet, in addition to `systemsmanagement:puppet` also the `devel:languages:ruby:backports` repository on OBS and the SLES SDK DVD is used. The placeholder in the AutoYaST SLES template has to be updated with the actual SDK URL. diff --git a/_includes/manuals/3.12/4.4.8.3_prov_windows.md b/_includes/manuals/3.12/4.4.8.3_prov_windows.md new file mode 100644 index 0000000000..bb86c29a71 --- /dev/null +++ b/_includes/manuals/3.12/4.4.8.3_prov_windows.md @@ -0,0 +1,183 @@ +Provisioning Windows is a two step process. The first step, [creating Installation Media](https://github.com/kireevco/wimaging), is not discussed here. +It includes getting the WIM files, updates and drivers and boot files ready. +The necessary boot files are are later downloaded by automatically by the smart proxy. + +##### Tasks break down +- Change / add a new Architecture and OS +- Edit provision templates +- Add installation media +- Edit partition table +- Add parameters +- Link provisioning templates to OS + +##### Architecture and OS +In _Hosts > Architectures_ add a new architecture: + +- Name: `x64` + +Add a new OS in _Hosts > Operating systems_ if needed. +If you already have Windows hosts and with Puppet installed, the correct OS and architecture will have been auto created already. +This example covers Windows 8.1 / Windows Server 2012R2. + +![Add new OS](/static/images/screenshots/4.4.8.3_prov_win_os.png "Adding Windows 8 OS in Foreman") + +- Name: `windows` +- Major: `6` +- Minor: `3` +- OS family: `windows` +- Description: `Windows8` +- Root password hash: `Base64` +- Architectures: `x64` + +Take special care to set __Root password hash = `Base64`__. The templates do not render correctly if this is set otherwise. +Changing the encoding does not [apply to existing hosts](/manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions). + +_Note:_ Foreman's [Safe Mode](/manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) does prevent using the password directly. +Thus, the string `AdminPassword` needs to be appended to your password when adding a new host. Eg `P@55w0rd` would become `P@55w0rdAdminPassword`. +This can be automated however by replacing the password part with a ruby function and disabling safe mode render. + +##### Add provision templates +Head to _Hosts > Provisioning Templates_ and edit the templates starting with `WAIK` to meet your needs. Make sure to get the latest version of the WAIK templates from the [community templates project](https://github.com/theforeman/community-templates). +Assign each of those templates to your Windows OS (does not apply to snippets). +The naming of the templates is a suggestion and up to you. This does __not__ apply to snippets! There, the name is important. + +_Note:_ You can find more info about [Foreman Template Writing in the documentation](https://docs.theforeman.org/{{ page.version }}/Managing_Hosts/index-foreman-el.html#Template_Writing_Reference_managing-hosts). + +##### Required templates +__WAIK Finish__ + + - Name: `WAIK Finish` + - Kind: Finish + + +__WAIK unattend.xml__ + + - Name: `WAIK unattend.xml` + - Kind: Provision + + +__WAIK peSetup.cmd__ + + - Name: `WAIK peSetup.cmd` + - Kind: Script + +_Note:_ To get the download folders nicely, the `wget` commands in this template might need tweaking. This could +especially be necessary if you intend to use the `extraFinishCommands` snippet. +Eg, `--cut-dirs=3` would cut the first three directories form the download path when saving locally. +This way `http://winmirror.domain.com/pub/win81x64/extras/puppet.msi` will be stripped of `pub/win81x64/extras` and download to `puppet.msi`. + +__WAIK PXELinux__ + + - Name: `WAIK PXELinux` + - Kind: PXE Linux + +##### Optional templates + +__WAIK joinDomain.ps1__ + + - Name: `WAIK joinDomain.ps1` + - Kind: User Data + +__WAIK local users__ + + - Name: `WAIK local users` + - Kind: Snippet + +_Note:_ This snippet creates extra users in the unattended stage. +This may be very useful for debugging early stages of your deployment; since you +can find yourself locked out of the newly provisioned host. + +Microsoft does not really care about password security in unattend.xml files; so it does not really matter if you use +`true</PlainText>` or not. If you prefer the encoded form, you need to append the string `Password` to your user password and encode it to Base64. The following ruby function is an example, it creates the _encoded_ from of `P@55w0rd`: + +``` +Base64.encode64(Encoding::Converter.new("UTF-8", "UTF-16LE",:undef => nil).convert("P@55w0rd"+"Password")).delete!("\n").chomp +``` + +__WAIK extraFinishCommands__ + + - Name: `WAIK extraFinishCommands` + - Kind: Snippet + +_Note:_ The commands here are executed at the last stage just before finishing host building. +Make sure they get executed in a synchronous way (eg. do not run in background like msiexec). +Otherwise the following reboot might kill them. + +__WAIK OU from host group__ + + - Name: `WAIK OU from host group` + - Kind: Snippet + +_Note:_ This snippet may be used to generate the computer OU from the host's host group and domain. + +_Example:_ Given a host `example` in domain `ad.corp.com` and in host group `servers/windows/databases`. +The snippet generates the OU path: +`OU=databases,OU=windows,OU=servers,DC=ad,DC=corp,DC=com`. Optionally, set the host parameter `computerOuSuffix` to add some arbitrary OU at the end. + +##### Add installation media +For each of your Windows versions add a new installation medium pointing to the root of the folder containing _boot_ and _sources_ +Eg, `http://winmirror.domain.com/pub/win81x64`. Assign them to your operating system. + +##### Modify partition table +The default partition table is a simple `diskpart.exe` script. It will wipe `Disk 0` + +##### Define templates +Link all the created templates as well as the installation media and partition table to the OS: + +1. Head to your OS, then provisioning +2. Select the template from each kind from the drop down list +3. In partition tables, select `WAIK default` +4. In installation media, check the appropriate installation media added above. + +![Link templates to OS](/static/images/screenshots/4.4.8.3_prov_win_templates.png "Linking Windows 8 OS in Foreman") + +##### Add Parameters +To render the templates correctly, some parameters need to be added. They need to be available as global/host parameters. Most of them make the most sense as parameter on the OS. Most parameters are not +required and have defaults. For the most up to date description see the template itself. + +##### Important parameters +__Required__ + +- `windowsLicenseKey`: Valid Windows license key or generic KMS key +- `windowsLicenseOwner`: Legal owner of the Windows license key +- `wimImageName`: WIM image to install from a multi image install.wim file + +_Note:_ The correct value for `wimImageName` depends on your _install.wim_. The provisioning _will fail_ an incorrect value is supplied for a multi image WIM file and gets silently ignored if the image contains one image only. + +__Optional__ +The following parameters are only applied if they exist. Some, like `domainJoinAccount` and `domainJoinAccountPasswd` require each other. + +- `systemLocale`: en-US +- `systemUILanguage`: en-US +- `systemTimeZone`: Pacific Standard Time - see [MS TimeZone Naming](https://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) +- `localAdminAccountDisabled`: false - will keep the local administrator account disabled (default windows) +- `ntpSever`: time.windows.com,other.time.server - ntp server to use +- `domainJoinAccount`: administrator@domain.com - use this account to join the computer to a domain +- `domainJoinAccountPasswd`: Pa55w@rd - Password for the domain join account +- `computerOU`: OU=Computers,CN=domain,CN=com - Place the computer account in specified Organizational Unit +- `computerOuSuffix`: Used if `computerOU` is not present to generate the computer OU from host group and host domain. `computerOU` takes precedence! Note, the OU must still be manually created in active directory +- `computerDomain`: domain.com - domain to join + +##### Troubleshooting + +__Templates__ + +The templates most likely need a lot of testing to work. This is not covered here; though some hints how to start. You should proceed in this order: + +1. __Get your templates to render correctly__. Create random `Bare Metal` host in the desired host group for this purpose and make extensive use of [Foreman's template preview feature](https://www.youtube.com/watch?v=KQnaRAI8rf4). +2. __Continue tesing with VMs__ to test netbooting and basic installation +3. __Debug `peSetup.cmd`__ by pausing it at the send (remove the comment from `::PAUSE`). Then, use `Ctrl-C` to cancel the script altogether. This way you can debug the rendered `peSetup.cmd` quite nicely in WinPE (eg, `notepad peSetup.cmd`) +3. The `WAIK Finish` template uses `sDelete.exe` to remove all rendered commands from the provided host. Comment out all `sDelete` commands to debug finish scripts. +4. Use a manual installed host to test rendered snippets like `WAIK extraFinishCommands` directly. +5. __Examine `C:\foreman.log.`__ - the output left from the finish script. Also, comment out the clean up stage in the finish script to examine and test the rendered scripts directly. + +__Netbooting__ + +Sometimes wimboot seems not to be able to boot our winPE.wim. Symptoms range from black screens to kernel panics (aka _BSOD_). These problems seem to be more likely on older hardware. + +In this case a workaround can be to simply use any other bootable media like USB thumb drives and CD-ROMs. The process is relatively simple: + +1. Use a common tool [Media Creator](http://windows.microsoft.com/en-us/windows-8/create-reset-refresh-media) to create a bootable medium like a USB stick or ISO image. Since we do not use the image downloaded by the tool, the only important choice is `architecture`. +2. In the image or the USB drive, replace `sources/boot.wim` with the version from the installation media. +3. Boot from the medium. + diff --git a/_includes/manuals/3.12/4.4.8_prov_os_notes.md b/_includes/manuals/3.12/4.4.8_prov_os_notes.md new file mode 100644 index 0000000000..096bba8ffe --- /dev/null +++ b/_includes/manuals/3.12/4.4.8_prov_os_notes.md @@ -0,0 +1 @@ +This chapter contains information about provisioning specific operating systems. diff --git a/_includes/manuals/3.12/4.4_provisioning.md b/_includes/manuals/3.12/4.4_provisioning.md new file mode 100644 index 0000000000..aaa65fa543 --- /dev/null +++ b/_includes/manuals/3.12/4.4_provisioning.md @@ -0,0 +1,2 @@ + +This chapter details the configuration of the required UI components necessary to provision an OS onto a host. diff --git a/_includes/manuals/3.12/4.5.1_cli_examples.md b/_includes/manuals/3.12/4.5.1_cli_examples.md new file mode 100644 index 0000000000..dfeb7b8647 --- /dev/null +++ b/_includes/manuals/3.12/4.5.1_cli_examples.md @@ -0,0 +1,89 @@ + +Basic help and list of supported commands: +{% highlight text %} +$ hammer -h +Usage: + hammer [OPTIONS] SUBCOMMAND [ARG] ... + +Parameters: + SUBCOMMAND subcommand + [ARG] ... subcommand arguments + +Subcommands: + architecture Manipulate architectures. + auth Foreman connection login/logout. + compute-resource Manipulate compute resources. + domain Manipulate domains. + environment Manipulate environments. + fact Search facts. + filter Manage permission filters. + global-parameter Manipulate global parameters. + host Manipulate hosts. + hostgroup Manipulate hostgroups. + location Manipulate locations. + medium Manipulate installation media. + model Manipulate hardware models. + organization Manipulate organizations. + os Manipulate operating system. + partition-table Manipulate partition tables. + proxy Manipulate smart proxies. + puppet-class Search puppet modules. + report Browse and read reports. + role Manage user roles. + sc-param Manipulate smart class parameters. + shell Interactive shell + subnet Manipulate subnets. + template Manipulate config templates. + user Manipulate users. + user-group Manage user groups. + +Options: + -v, --verbose be verbose + -c, --config CFG_FILE path to custom config file + -u, --username USERNAME username to access the remote system + -p, --password PASSWORD password to access the remote system + --version show version + --show-ids Show ids of associated resources + --csv Output as CSV (same as --adapter=csv) + --output ADAPTER Set output format. One of [base, table, silent, csv] + --csv-separator SEPARATOR Character to separate the values + -P, --ask-pass Ask for password + --autocomplete LINE Get list of possible endings + -h, --help print help +{% endhighlight %} + +First level command help: +{% highlight text %} +$ hammer architecture -h +Usage: + hammer architecture [OPTIONS] SUBCOMMAND [ARG] ... + +Parameters: + SUBCOMMAND subcommand + [ARG] ... subcommand arguments + +Subcommands: + list List all architectures. + info Show an architecture. + create Create an architecture. + delete Delete an architecture. + update Update an architecture. + add_operatingsystem Associate a resource + remove_operatingsystem Disassociate a resource + +Options: + -h, --help print help +{% endhighlight %} + +Second level command help: +{% highlight text %} +$ hammer architecture create -h +Usage: + hammer architecture create [OPTIONS] + +Options: + --name NAME + --operatingsystem-ids OPERATINGSYSTEM_IDS + Operatingsystem ID’s + -h, --help print help +{% endhighlight %} diff --git a/_includes/manuals/3.12/4.5.2_cli_success.md b/_includes/manuals/3.12/4.5.2_cli_success.md new file mode 100644 index 0000000000..f60b8fcf47 --- /dev/null +++ b/_includes/manuals/3.12/4.5.2_cli_success.md @@ -0,0 +1,86 @@ + +There was a set of common commands identified as necessary for basic Foreman management, we called it "success story" and [track](http://projects.theforeman.org/issues/3297) the progress of its implementation. The commands could also serve as a basic hammer cookbook. + +The goal is to provision bare metal host on a clean install of Foreman. The following steps are necessary: + +* create smart proxy +``` +hammer proxy create --name myproxy --url https://proxy.my.net:8443 +``` +* create architecture +``` +hammer architecture create --name x86_64 +``` +* create new subnet +``` +hammer subnet create --name "My Net" --network "192.168.122.0" --mask "255.255.255.0" --gateway "192.168.122.1" --dns-primary "192.168.122.1" +``` +* import existing subnet from a proxy + + missing, see [#3355](http://projects.theforeman.org/issues/3355) +* create new domain +``` +hammer domain create --name "my.net" --fullname "My network" +``` +* associate domain with proxy +``` +hammer domain update --id 1 --dns-id 1 +``` +* associate subnet with domain +``` +hammer subnet update --id 1 --domain-ids 1 +``` +* associate subnet with proxy (DHCP, TFTP, DNS) +``` +hammer subnet update --id 1 --dhcp-id 1 --tftp-id 1 --dns-id 1 +``` +* create new partition table +``` +hammer partition_table create --name "Redhat test" --file /tmp/rh_test.txt +``` +* create new OS +``` +hammer os create --name RHEL --major 6 --minor 4 +``` +* create new template +``` +hammer template create --name "kickstart mynet" --type provision --file /tmp/ks.txt +``` +* edit existing pre-defined template +``` +hammer template dump --id 4 > /tmp/ks.txt + vim /tmp/ks.txt +hammer template update --id 4 --file /tmp/ks.txt +``` +* associate applicable OS with pre-defined template +``` +hammer template update --id 1 --operatingsystem-ids 1 +``` + + Listing associated OS's is still missing - see [#3360](http://projects.theforeman.org/issues/3360) + +* associate OS with architecture +``` +hammer os update --id 1 --architecture-ids 1 +``` +* associate OS with part table +``` +hammer os update --id 1 --ptable-ids 1 +``` +* associate OS with install media +``` +hammer os update --id 1 --medium-ids 1 +``` +* associate OS with install provision and pxelinux templates + + Missing, needs investigation, may be related to [#3360](http://projects.theforeman.org/issues/3360) +* create libvirt compute resource +``` +hammer compute_resource create --name libvirt --url "qemu:///system" --provider Libvirt +``` +* import puppet classes + + missing - see [#3035](http://projects.theforeman.org/issues/3035) +* and finally create a bare metal host entry + + works with some options, needs improvements - see [#3063](http://projects.theforeman.org/issues/3063) diff --git a/_includes/manuals/3.12/4.5_cli.md b/_includes/manuals/3.12/4.5_cli.md new file mode 100644 index 0000000000..3e2d46568e --- /dev/null +++ b/_includes/manuals/3.12/4.5_cli.md @@ -0,0 +1 @@ +The framework used for implementation of command line client for foreman provides many features common for modern CLI applications. The task of managing Foreman from command line is quite complex so the commands have to be organized in more levels of subcommands. There is help available for each level to make it easy to use. Some other features for greater comfort are option validation, logging and customizable output formatting. diff --git a/_includes/manuals/3.12/4.6.1_email_preferences.md b/_includes/manuals/3.12/4.6.1_email_preferences.md new file mode 100644 index 0000000000..97171f4dff --- /dev/null +++ b/_includes/manuals/3.12/4.6.1_email_preferences.md @@ -0,0 +1,14 @@ + +#### Users + +Email messages are sent to individual users registered to Foreman, to the email address configured on the account if present. Users can edit the email address by clicking on their name in the top-right hand corner of the web page and selecting *My account*. + +To change which message subscriptions are received by an individual user, the *Mail Preferences* tab under the user account lists all available message types and the frequency at which each message should be received. A global checkbox to disable all email messages from Foreman is also available. + +Event-based notifications can either be enabled or disabled, and these are sent from Foreman at the same time as the event occurring. Scheduled notifications can be sent either daily, weekly or monthly. + +#### Hosts + +Notifications relating to hosts can be disabled on a per-host basis, useful when errors are expected. On the host's *Additional Information* tab, untick *Enabled* to disable notifications and remove the host from reports. Enabling and disabling notifications can also be done from the host list by using the tickboxes and selecting *Enable/Disable Notifications* from the *Select Action* dropdown menu. + +Event notifications for a host are sent to the host's registered owner. This is selected on the *Additional Information* tab of the host, and may be either an individual user or a user group. When set to a user group, all group members who are subscribed to the email type will receive a message. diff --git a/_includes/manuals/3.12/4.6.2_email_account.md b/_includes/manuals/3.12/4.6.2_email_account.md new file mode 100644 index 0000000000..e722c0e8d6 --- /dev/null +++ b/_includes/manuals/3.12/4.6.2_email_account.md @@ -0,0 +1,4 @@ + +#### New account welcome email + +When the `send_welcome_email` setting is enabled ([Configuration Options](/manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions)), new account holders will receive an email providing their username and a link to Foreman. diff --git a/_includes/manuals/3.12/4.6.3_email_host.md b/_includes/manuals/3.12/4.6.3_email_host.md new file mode 100644 index 0000000000..b07a474dce --- /dev/null +++ b/_includes/manuals/3.12/4.6.3_email_host.md @@ -0,0 +1,8 @@ + +#### Build complete + +When a host has completed its build process, either notifying Foreman of completion via a request at the end of its unattended installation or after Foreman has run a script remotely, this email notification will be sent to owners of the host. + +#### Puppet error state + +When a Puppet report is received that puts the host into a red error state, a corresponding email notification is sent to owners of the host. diff --git a/_includes/manuals/3.12/4.6.4_email_scheduled.md b/_includes/manuals/3.12/4.6.4_email_scheduled.md new file mode 100644 index 0000000000..47e8961f1a --- /dev/null +++ b/_includes/manuals/3.12/4.6.4_email_scheduled.md @@ -0,0 +1,8 @@ + +#### Audit summary + +A regular summary email of all changes to objects in Foreman that triggered audit events (see [Auditing](/manuals/{{page.version}}/index.html#4.1.4Auditing)), including the user that made the change, the time of the change and a link to further details. + +#### Puppet summary + +A regular overview of all hosts that a user has access to, and their Puppet status. This includes the number of Puppet events over the reporting period, such as applied, skipped and failed resources. diff --git a/_includes/manuals/3.12/4.6_email.md b/_includes/manuals/3.12/4.6_email.md new file mode 100644 index 0000000000..8feca7619c --- /dev/null +++ b/_includes/manuals/3.12/4.6_email.md @@ -0,0 +1,6 @@ + +Foreman is also able to send out a variety of email notifications either on an event, or summary messages on a regular schedule. Plugins are also able to extend this with their own summaries and notifications. + +To send email requires a configured SMTP server or local MTA (e.g. sendmail), which is set up in `Adminster > Settings > Email` as per [Configuration Options](/manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions). + +Scheduled emails are sent through rake tasks (reports:daily, reports:weekly, reports:monthly) run from cronjobs, which are configured in `/etc/cron.d/foreman`. diff --git a/_includes/manuals/3.12/4.7_managing_ansible.md b/_includes/manuals/3.12/4.7_managing_ansible.md new file mode 100644 index 0000000000..90306b380b --- /dev/null +++ b/_includes/manuals/3.12/4.7_managing_ansible.md @@ -0,0 +1 @@ +Please refer to the [foreman_ansible plugin documentation](/plugins/foreman_ansible/). diff --git a/_includes/manuals/3.12/4.8_managing_chef.md b/_includes/manuals/3.12/4.8_managing_chef.md new file mode 100644 index 0000000000..b85df5449b --- /dev/null +++ b/_includes/manuals/3.12/4.8_managing_chef.md @@ -0,0 +1 @@ +The `foreman_chef` plugin has been removed. diff --git a/_includes/manuals/3.12/4.9_managing_salt.md b/_includes/manuals/3.12/4.9_managing_salt.md new file mode 100644 index 0000000000..81ced0c194 --- /dev/null +++ b/_includes/manuals/3.12/4.9_managing_salt.md @@ -0,0 +1 @@ +Documentation: [Using Salt for Configuration Management](https://docs.theforeman.org/nightly/Managing_Hosts/index-foreman-el.html#Using_Salt_for_Configuration_Management_managing-hosts) diff --git a/_includes/manuals/3.12/4_general_foreman.md b/_includes/manuals/3.12/4_general_foreman.md new file mode 100644 index 0000000000..16ef39d72a --- /dev/null +++ b/_includes/manuals/3.12/4_general_foreman.md @@ -0,0 +1,2 @@ + +This section covers general information on using Foreman to manage your infrastructure. It covers the features of the web interface, managing puppet, provisioning systems and the installation and configuration of Foreman Smart Proxies. diff --git a/_includes/manuals/3.12/5.1.10_apipie-bindings.md b/_includes/manuals/3.12/5.1.10_apipie-bindings.md new file mode 100644 index 0000000000..c2e1c64994 --- /dev/null +++ b/_includes/manuals/3.12/5.1.10_apipie-bindings.md @@ -0,0 +1,101 @@ +The following examples show how to do basic API operations using [apipie-bindings](https://github.com/Apipie/apipie-bindings). + +#### Show a Collection of Objects + +Get of a collection of domains: `GET /api/domains` + +Call the **index** function of the **domains** resource. + +```ruby +#!/usr/bin/env ruby + +require 'apipie-bindings' + +url = 'https://foreman.example.com/' +username = 'admin' +password = 'changeme' +api = ApipieBindings::API.new({:uri => url, :username => username, :password => password, :api_version => '2'}) +domains = api.resource(:domains).call(:index) + +domains['results'].each do |domain| + puts domain +end +``` + +```console +$ ruby domains.rb +{"fullname"=>"", "dns_id"=>1, "created_at"=>"2016-05-06 08:46:20 UTC", "updated_at"=>"2016-11-24 11:49:06 UTC", "id"=>1, "name"=>"example.com"} +``` + +#### Show a Single Object + +Get a single domain: `GET /api/domains/:id` or `GET /api/domains/:name` + +Call the **show** function of the **domains** resource with the object's unique identifier `:id` or `:name`. + +```ruby +#!/usr/bin/env ruby + +require 'apipie-bindings' + +url = 'https://foreman.example.com/' +username = 'admin' +password = 'changeme' +api = ApipieBindings::API.new({:uri => url, :username => username, :password => password, :api_version => '2'}) +puts api.resource(:domains).call(:show, {:id => 1}) +puts api.resource(:domains).call(:show, {:id => 'example.com'}) +``` + +#### Create an Object + +Create a new domain: `POST /api/domains` + +Call the **create** function of the **domains** resource with a JSON data hash containing the required fields to create the object. In this example, a domain is being created. + +```ruby +#!/usr/bin/env ruby + +require 'apipie-bindings' + +url = 'https://foreman.example.com/' +username = 'admin' +password = 'changeme' +api = ApipieBindings::API.new({:uri => url, :username => username, :password => password, :api_version => '2'}) +api.resource(:domains).call(:create, {:domain => {:name => "foo.example.com", :fullname => "foo.example.com"}}) +``` + +#### Update an Object + +Update a domain: `PUT /api/domains/:id` or `PUT /api/domains/:name` + +Call the **update** function of the **domains** resource with the object's unique identifier, either `:id` or `:name`, plus a JSON data hash containing only the data to be updated. In this example, only the domain name is being updated. + +```ruby +#!/usr/bin/env ruby + +require 'apipie-bindings' + +url = 'https://foreman.example.com/' +username = 'admin' +password = 'changeme' +api = ApipieBindings::API.new({:uri => url, :username => username, :password => password, :api_version => '2'}) +api.resource(:domains).call(:update, {:id => 3, :domain => {:name => "foo.example.com", :fullname => "foo.example.com"}}) +``` + +#### Delete an Object + +Delete a domain: `DELETE /api/domains/:id` or `DELETE /api/domains/:name` + +Call the **destroy** function of the **domains** resource with the object's unique identifier, either `:id` or `:name`. + +```ruby +#!/usr/bin/env ruby + +require 'apipie-bindings' + +url = 'https://foreman.example.com/' +username = 'admin' +password = 'changeme' +api = ApipieBindings::API.new({:uri => url, :username => username, :password => password, :api_version => '2'}) +api.resource(:domains).call(:destroy, {:id => 3}) +``` diff --git a/_includes/manuals/3.12/5.1.11_graphql.md b/_includes/manuals/3.12/5.1.11_graphql.md new file mode 100644 index 0000000000..97a18adfae --- /dev/null +++ b/_includes/manuals/3.12/5.1.11_graphql.md @@ -0,0 +1,69 @@ +The following examples show how to do basic API operations using [GraphQL](https://graphql.org/). + +#### Access the API + +The GraphqlAPI is available at `/api/graphql`. + +#### Query the API with curl + +This command shows how you can query the API with curl. + +```bash +curl -u username:password -X POST -H "Content-Type: application/json" --data '{ "query": "{ domains { nodes { name } } }" }' https://foreman.example.com/api/graphql +``` + +#### Show a Collection of Objects + +Get of a collection of domains: + +Query: +```graphql +{ + domains(search: "name ~ example.com") { + nodes { + name + } + } +} +``` + +Result: +```json +{ + "data": { + "domains": { + "nodes": [ + { + "name": "example.com" + } + ] + } + } +} +``` + +#### Show a Single Object + +Get a single domain: + +Query: +```graphql +{ + domain(id: "MDE6RG9tYWluLTQ=") { + name, + createdAt + } +} +``` + +Result: +```json +{ + "data": { + "domain": { + "name": "example.com", + "createdAt": "2017-01-18T11:12:52+01:00" + } + } +} +``` diff --git a/_includes/manuals/3.12/5.1.12_dynflow_scaling.md b/_includes/manuals/3.12/5.1.12_dynflow_scaling.md new file mode 100644 index 0000000000..4b9aa1705c --- /dev/null +++ b/_includes/manuals/3.12/5.1.12_dynflow_scaling.md @@ -0,0 +1,172 @@ +Starting with Foreman 2.0 Foreman uses Dynflow backed by Sidekiq by default on all supported platforms. This change is described in greater detail in [Upcoming changes to Dynflow](https://community.theforeman.org/t/upcoming-changes-to-dynflow/14926). The original Dynflow executor service (called `dynflowd`) was replaced by `redis` and a set of `dynflow-sidekiq@*` services. This new deployment model should address issues we have seen when restarting the Dynflow executor. It also allows us scale more easily, dedicate workers to specific queues and increase the overall throughput. The following examples show how to scale Dynflow up in the new model. + +### Clean state + +Out of the box, foreman ships with orchestrator and a single worker +If you have Katello, you will get an additional worker for processing of the host queue +``` +# ls -l /etc/foreman/dynflow/ +total 1 +-rw-r--r--. 1 root foreman 51 May 14 07:35 orchestrator.yml +-rw-r--r--. 1 root foreman 59 May 14 07:35 worker.yml +``` + +The orchestrator consumes items only from the `dynflow_orchestrator` queue and has only one thread. This is by design. *Do not change this* +``` +# cat /etc/foreman/dynflow/orchestrator.yml +:concurrency: 1 +:queues: + - dynflow_orchestrator +``` + +The regular worker has 5 threads and consumes items from +default and remote_execution queues. It is not recommended +to change the configuration for this process either, because the changes +would be overwritten by the installer, if run again. + +``` +# cat /etc/foreman/dynflow/worker.yml +:concurrency: 5 +:queues: + - default + - remote_execution +``` + +### Scaling up +Scaling up is pretty straightforward, especially if you want to only scale up what you have +Here we use symbolic links to "share" the actual configuration among `worker`, `worker-1` and `worker-2` +``` +# cd /etc/foreman/dynflow +# ln -s worker.yml worker-1.yml +# ln -s worker.yml worker-2.yml +``` + +Check that the symbolic links are pointing to the right files +``` +# ls -l /etc/foreman/dynflow/ +total 2 +-rw-r--r--. 1 root foreman 51 May 14 07:35 orchestrator.yml +lrwxrwxrwx. 1 root root 10 May 14 11:24 worker-1.yml -> worker.yml +lrwxrwxrwx. 1 root root 10 May 14 11:24 worker-2.yml -> worker.yml +-rw-r--r--. 1 root foreman 59 May 14 07:35 worker.yml +``` + +Now start the newly configured services and check their status +``` +# systemctl enable --now dynflow-sidekiq@worker-{1,2} +Created symlink /etc/systemd/system/multi-user.target.wants/dynflow-sidekiq@worker-1.service → /lib/systemd/system/dynflow-sidekiq@.service. +Created symlink /etc/systemd/system/multi-user.target.wants/dynflow-sidekiq@worker-2.service → /lib/systemd/system/dynflow-sidekiq@.service. + +# systemctl status dynflow-sidekiq@worker-{1,2} +● dynflow-sidekiq@worker-1.service - Foreman jobs daemon - worker-1 on sidekiq + Loaded: loaded (/lib/systemd/system/dynflow-sidekiq@.service; enabled; vendor preset: enabled) + Active: active (running) since Thu 2020-05-14 11:24:19 UTC; 6s ago + Docs: https://theforeman.org + Main PID: 1422 (ruby2.5) + Tasks: 5 (limit: 38437) + Memory: 175.9M + CGroup: /system.slice/system-dynflow\x2dsidekiq.slice/dynflow-sidekiq@worker-1.service + └─1422 ruby2.5 /usr/share/foreman/vendor/ruby/2.5.0/bin/sidekiq -e production -r /usr/share/foreman/extras/dynflow-sidekiq.rb -C /etc/foreman/dynflow/worker-1.yml + +May 14 11:24:19 modest-gator systemd[1]: Started Foreman jobs daemon - worker-1 on sidekiq. +May 14 11:24:21 modest-gator dynflow-sidekiq@worker-1[1422]: 2020-05-14T11:24:21.442Z 1422 TID-gpznscy7m INFO: GitLab reliable fetch activated! +May 14 11:24:21 modest-gator dynflow-sidekiq@worker-1[1422]: 2020-05-14T11:24:21.443Z 1422 TID-gpzo69up6 INFO: Booting Sidekiq 5.2.8 with redis options {:id=>"Sidekiq-server-PID-1422", :url=>"redis://localhost:6379/0"} + +● dynflow-sidekiq@worker-2.service - Foreman jobs daemon - worker-2 on sidekiq + Loaded: loaded (/lib/systemd/system/dynflow-sidekiq@.service; enabled; vendor preset: enabled) + Active: active (running) since Thu 2020-05-14 11:24:19 UTC; 6s ago + Docs: https://theforeman.org + Main PID: 1423 (ruby2.5) + Tasks: 5 (limit: 38437) + Memory: 178.4M + CGroup: /system.slice/system-dynflow\x2dsidekiq.slice/dynflow-sidekiq@worker-2.service + └─1423 ruby2.5 /usr/share/foreman/vendor/ruby/2.5.0/bin/sidekiq -e production -r /usr/share/foreman/extras/dynflow-sidekiq.rb -C /etc/foreman/dynflow/worker-2.yml + +May 14 11:24:19 modest-gator systemd[1]: Started Foreman jobs daemon - worker-2 on sidekiq. +May 14 11:24:21 modest-gator dynflow-sidekiq@worker-2[1423]: 2020-05-14T11:24:21.448Z 1423 TID-gpcxyxoi7 INFO: GitLab reliable fetch activated! +May 14 11:24:21 modest-gator dynflow-sidekiq@worker-2[1423]: 2020-05-14T11:24:21.449Z 1423 TID-gpcyculz7 INFO: Booting Sidekiq 5.2.8 with redis options {:id=>"Sidekiq-server-PID-1423", :url=>"redis://localhost:6379/0"} +``` + +### Scaling down +Scaling down is just reverse process, let's say having `worker`, `worker-1` and `worker-2` was +an overkill and we think we would be fine with just `worker` and `worker-1`. +``` +# systemctl disable --now dynflow-sidekiq@worker-2 +Removed /etc/systemd/system/multi-user.target.wants/dynflow-sidekiq@worker-2.service. + +# rm /etc/foreman/dynflow/worker-2.yml +``` + +### Dedicating a worker to a queue +For this we need to create a new configuration for a worker (or just copy an existing one and change the relevant lines) + +Create the configuration file, here we create a worker called `rex` having 5 threads and consuming items from the `remote_execution` queue +``` +# cat <<EOF >/etc/foreman/dynflow/rex.yml +:concurrency: 5 +:queues: + - remote_execution +EOF +``` + +Now let's start the service and check its status +``` +# systemctl start dynflow-sidekiq@rex + +# systemctl status dynflow-sidekiq@rex +● dynflow-sidekiq@rex.service - Foreman jobs daemon - rex on sidekiq + Loaded: loaded (/lib/systemd/system/dynflow-sidekiq@.service; disabled; vendor preset: enabled) + Active: active (running) since Thu 2020-05-14 11:32:01 UTC; 3s ago + Docs: https://theforeman.org + Main PID: 1785 (ruby2.5) + Tasks: 5 (limit: 38437) + Memory: 115.8M + CGroup: /system.slice/system-dynflow\x2dsidekiq.slice/dynflow-sidekiq@rex.service + └─1785 ruby2.5 /usr/share/foreman/vendor/ruby/2.5.0/bin/sidekiq -e production -r /usr/share/foreman/extras/dynflow-sidekiq.rb -C /etc/foreman/dynflow/rex.yml + +May 14 11:32:01 modest-gator systemd[1]: Started Foreman jobs daemon - rex on sidekiq. +May 14 11:32:02 modest-gator dynflow-sidekiq@rex[1785]: 2020-05-14T11:32:02.789Z 1785 TID-gpaz8n321 INFO: GitLab reliable fetch activated! +May 14 11:32:02 modest-gator dynflow-sidekiq@rex[1785]: 2020-05-14T11:32:02.790Z 1785 TID-gpazi1pg1 INFO: Booting Sidekiq 5.2.8 with redis options {:id=>"Sidekiq-server-PID-1785", :url=>"redis://localhost:6379/0"} +``` + +### Tuning number of threads per worker +The only thing that needs to be done is changing the number at the `:concurrency:` line and restarting the service. +Either open it up in your favourite `$EDITOR` or do it with `sed`. + +Here we can see the worker from previous example has 5 threads. `1785` is the process id taken from previous invocation of systemctl status +``` +# ps -fp 1785 +foreman 1785 1 0 11:32 ? 00:00:14 sidekiq 5.2.8 [0 of 5 busy] +``` + +Next we change it to 15 +``` +# sed -i 's/:concurrency: .*/:concurrency: 15/' /etc/foreman/dynflow/rex.yml +``` + +Restart the service and check its status +``` +# systemctl restart dynflow-sidekiq@rex + +# systemctl status dynflow-sidekiq@rex +● dynflow-sidekiq@rex.service - Foreman jobs daemon - rex on sidekiq + Loaded: loaded (/lib/systemd/system/dynflow-sidekiq@.service; disabled; vendor preset: enabled) + Active: active (running) since Thu 2020-05-14 11:34:20 UTC; 2s ago + Docs: https://theforeman.org + Main PID: 1903 (ruby2.5) + Tasks: 4 (limit: 38437) + Memory: 94.4M + CGroup: /system.slice/system-dynflow\x2dsidekiq.slice/dynflow-sidekiq@rex.service + └─1903 ruby2.5 /usr/share/foreman/vendor/ruby/2.5.0/bin/sidekiq -e production -r /usr/share/foreman/extras/dynflow-sidekiq.rb -C /etc/foreman/dynflow/rex.yml + +May 14 11:34:20 modest-gator systemd[1]: Started Foreman jobs daemon - rex on sidekiq. +May 14 11:34:21 modest-gator dynflow-sidekiq@rex[1903]: 2020-05-14T11:34:21.852Z 1903 TID-gn2jupy2z INFO: GitLab reliable fetch activated! +May 14 11:34:21 modest-gator dynflow-sidekiq@rex[1903]: 2020-05-14T11:34:21.852Z 1903 TID-gn2k8l9cr INFO: Booting Sidekiq 5.2.8 with redis options {:id=>"Sidekiq-server-PID-1903", :url=>"redis://localhost:6379/0"} +``` + +And finally we can check it has more threads. +``` +# ps -fp 1903 +UID PID PPID C STIME TTY TIME CMD +foreman 1903 1 0 11:34 ? 00:00:14 sidekiq 5.2.8 [0 of 15 busy] +``` diff --git a/_includes/manuals/3.12/5.1.1_request_examples.md b/_includes/manuals/3.12/5.1.1_request_examples.md new file mode 100644 index 0000000000..3f26b327a7 --- /dev/null +++ b/_includes/manuals/3.12/5.1.1_request_examples.md @@ -0,0 +1,77 @@ +The following examples show the basic CRUD operations (Create, Read, Update, Delete) using the JSON API. + +&nbsp; + +#### Show a Collection of Objects + +Get of a collection of domains: `GET /api/domains` + +Send a HTTP **GET** request. No JSON data hash is required. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" https://foreman.example.com/api/domains + +This returns a collection JSON response. The format for a collection response is described in [Section 5.1.2](manuals/{{page.version}}/index.html#5.1.2JSONResponseFormatforCollections). + +&nbsp; + +#### Show a Single Object + +Get a single domain: `GET /api/domains/:id` or `GET /api/domains/:name` + +Send a HTTP **GET** request with the object's unique identifier, either `:id` or `:name`. No JSON data hash is required. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains/42 + # or + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains/foo + +This returns a single object in JSON format. The format for a single object response is described in [Section 5.1.3](manuals/{{page.version}}/index.html#5.1.3JSONResponseFormatforSingleObjects). + +&nbsp; + +#### Create an Object + +Create a new domain: `POST /api/domains` + +Send a HTTP **POST** request with a JSON data hash containing the required fields to create the object. In this example, a domain is being created. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" -H "Content-Type: application/json" \ + -X POST -d '{ "name":"foo.bar.com","fullname":"foo.bar.com description" }' \ + https://foreman.example.com/api/domains + +This returns the newly created object in JSON format, with the same attributes as in the show/GET call. The format for a single object response is described in [Section 5.1.3](manuals/{{page.version}}/index.html#5.1.3JSONResponseFormatforSingleObjects). + +The HTTP response code of the create call will be 201, if created successfully. + +&nbsp; + +#### Update an Object + +Update a domain: `PUT /api/domains/:id` or `PUT /api/domains/:name` + +Send a HTTP **PUT** request with the object's unique identifier, either `:id` or `:name`, plus a JSON data hash containing only the data to be updated. In this example, only the domain name is being updated. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" -H "Content-Type: application/json" \ + -X PUT -d '{ "name": "a new name" }' https://foreman.example.com/api/domains/12 + # or + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" -H "Content-Type: application/json" \ + -X PUT -d '{ "name": "a new name" }' https://foreman.example.com/api/domains/foo + +This returns the newly updated object in JSON format. The format for a single object response is described in [Section 5.1.3](manuals/{{page.version}}/index.html#5.1.3JSONResponseFormatforSingleObjects). + +&nbsp; + +#### Delete an Object + +Delete a domain: `DELETE /api/domains/:id` or `DELETE /api/domains/:name` + +Send a HTTP **DELETE** request with the object's unique identifier, either `:id` or `:name`. No JSON data hash is required. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" -X DELETE \ + https://foreman.example.com/api/domains/17 + # or + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" -X DELETE \ + https://foreman.example.com/api/domains/foo + +This returns the deleted object in JSON format. The format for a single object response is described in [Section 5.1.3](manuals/{{page.version}}/index.html#5.1.3JSONResponseFormatforSingleObjects). diff --git a/_includes/manuals/3.12/5.1.2_api_json_collections.md b/_includes/manuals/3.12/5.1.2_api_json_collections.md new file mode 100644 index 0000000000..65a7493639 --- /dev/null +++ b/_includes/manuals/3.12/5.1.2_api_json_collections.md @@ -0,0 +1,55 @@ +Collections are a list of objects (i.e. hosts, domains, etc). The format for a collection JSON response consists of a `results` root node and metadata fields `total, subtotal, page, per_page`. Note: for Katello objects, the metadata includes `limit, offset` instead of `page, per_page`. + +Below is an example of the format for a collection JSON response for a list of domains: `GET /api/domains` + + { + "total": 3, + "subtotal": 3, + "page": 1, + "per_page": 20, + "search": null, + "sort": { + "by": null, + "order": null + }, + "results": [ + { + "id": 23, + "name": "qa.lab.example.com", + "fullname": "QA", + "dns_id": 10, + "created_at": "2013-08-13T09:02:31Z", + "updated_at": "2013-08-13T09:02:31Z" + }, + { + "id": 25, + "name": "sat.lab.example.com", + "fullname": "SATLAB", + "dns_id": 8, + "created_at": "2013-08-13T08:32:48Z", + "updated_at": "2013-08-14T07:04:03Z" + }, + { + "id": 32, + "name": "hr.lab.example.com", + "fullname": "HR", + "dns_id": 8, + "created_at": "2013-08-16T08:32:48Z", + "updated_at": "2013-08-16T07:04:03Z" + } + ] + } + +The response metadata fields are described below: + +* `total` - total number of objects without any search parameters +* `subtotal` - number of objects returned with given search parameters (if there is no search, then `subtotal` equals `total`) +* `page` (Foreman only) - page number +* `per_page` (Foreman only) - maximum number of objects returned per page +* `limit` - (Katello only) specified number of objects to return in collection response +* `offset` - (Katello only) number of objects skipped before beginning to return collection. +* `search` - search string (based on scoped_scoped syntax) +* `sort` + * `by` - the field that the collection is sorted by + * `order` - sort order, either ASC for ascending or DESC for descending +* `results` - collection of objects. See [Section 5.1.4](manuals/{{page.version}}/index.html#5.1.4CustomizeJSONResponses) for how to change the root name from 'results' to something else. diff --git a/_includes/manuals/3.12/5.1.3_api_json_single_objects.md b/_includes/manuals/3.12/5.1.3_api_json_single_objects.md new file mode 100644 index 0000000000..bf58850066 --- /dev/null +++ b/_includes/manuals/3.12/5.1.3_api_json_single_objects.md @@ -0,0 +1,12 @@ +Single object JSON responses are used to show a single object. The object's unique identifier `:id` or `:name` is required in the **GET** request. Note that `:name` may not always be used as a unique identifier, but `:id` can always be used. The format for a single object JSON response consists of only the object's attributes. There is **no root node** and **no metadata** by default. See [Section 5.1.4](manuals/{{page.version}}/index.html#5.1.4CustomizeJSONResponses) for how to add a root name. + +Below is an example of the format for a single object JSON response: `GET /api/domains/23` or `GET /api/domains/qa.lab.example.com` + + { + "id": 23, + "name": "qa.lab.example.com", + "fullname": "QA", + "dns_id": 10, + "created_at": "2013-08-13T09:02:31Z", + "updated_at": "2013-08-13T09:02:31Z" + } diff --git a/_includes/manuals/3.12/5.1.4_api_customize.md b/_includes/manuals/3.12/5.1.4_api_customize.md new file mode 100644 index 0000000000..3aa500d51c --- /dev/null +++ b/_includes/manuals/3.12/5.1.4_api_customize.md @@ -0,0 +1,70 @@ + +#### Customize Root Node for Collections + +The default root node name for collections is `results` but can be changed. + +To change the root node name per API request, pass `root_name=` as a URL parameter. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains?root_name=data + +&nbsp; + +#### Customize Root Node for Single Object + +There is no root node as the default for single object JSON responses, but it can be added. + +To change the object's root node name per API request, pass `object_name=` as a URL parameter. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains/23?object_name=record + +&nbsp; + +#### Customize Partial Response Attributes + +Currently, there is no option to change or customize which attributes are returned for collections or single objects. In the future, customized partial responses such as `fields=field1,field2,field3` or `fields=all` may be implemented ([#3019](http://projects.theforeman.org/issues/3019)). Similarly, there is currently no option to specify child nodes in an API call or to remove child nodes if they are returned by default. + +&nbsp; + +#### Custom Number of Objects in Collection Per Response + +Foreman paginates all collections in the JSON response. The number of objects returned per request is defined in *Administer > Settings > General > entries_per_page*. The default is 20. Thus, if there are 27 objects in a collection, only 20 will be returned for the default page=1. + +To view the next page, pass `page=` as a URL parameter. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains?page=2 + +The example above will show the remaining 7 objects in our example of 27 objects in the collection. + +To increase or decrease the number of objects per response, pass `per_page=` as a URL parameter. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains?per_page=1000 + +This will return all the objects in one request since 27 is less than the `per_page` parameter set to 1000. + +&nbsp; + +#### Custom Search of Collections Per Response + +Foreman uses the scoped_search library for searching and filtering which allows all query search parameters to be specified in one string. The syntax is described in the [Searching](/manuals/{{page.version}}/index.html#4.1.5Searching) section, and matches exactly the syntax used for the web UI search boxes. This allows you use of the auto-completer and to test a query in the UI before reusing it in the API. + +To filter results of a collection, pass `search=` as a URL parameter, ensuring that it is fully URL-escaped to prevent search operators being misinterpreted as URL separators. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains?search=name%3Dexample.com + +The number of objects returned will be shown in the `subtotal` metadata field, and the query string will be shown in the `search` metadata field. + +&nbsp; + +#### Custom Sort of Collections Per Response + +Custom sort order per collection can be specified by passing `order=` as a URL parameter. See example below: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + https://foreman.example.com/api/domains?order=name+DESC + +The default sort order is ascending (ASC) if only a field name is passed. The sort parameters will be shown in `sort` `by` and `order` metadata fields. diff --git a/_includes/manuals/3.12/5.1.5_nested_api_routes.md b/_includes/manuals/3.12/5.1.5_nested_api_routes.md new file mode 100644 index 0000000000..ec11d78f76 --- /dev/null +++ b/_includes/manuals/3.12/5.1.5_nested_api_routes.md @@ -0,0 +1,11 @@ +The goal is to implement nested routes for all objects as an alternative to filtering collections. + +For example, rather then filtering subnets by a specified domain using a search string + + $ GET /api/subnets?search=name%3Dqa.lab.example.com + +the alternative nested route below returns the same result as the above. + + $ GET /api/domains/qa.lab.example.com/subnets + +All actions will be accessible in the nested route as in the main route. diff --git a/_includes/manuals/3.12/5.1.6_versioning.md b/_includes/manuals/3.12/5.1.6_versioning.md new file mode 100644 index 0000000000..bb064d4f41 --- /dev/null +++ b/_includes/manuals/3.12/5.1.6_versioning.md @@ -0,0 +1,9 @@ +The default API version is v2 for Foreman {{page.version}}, however explicitly requesting the version is recommended. Both API v1 and v2 are currently shipped. + +There are two methods of selecting an API version: + +1. In the **header**, pass `Accept: application/json,version=2` + +2. In the **URL**, pass /v2/ such as `GET /api/v2/hosts` + +Similarly, v1 can still be used by passing `Accept: application/json,version=1` in the header or `api/v1/` in the URL. diff --git a/_includes/manuals/3.12/5.1.7_associations.md b/_includes/manuals/3.12/5.1.7_associations.md new file mode 100644 index 0000000000..231662fe08 --- /dev/null +++ b/_includes/manuals/3.12/5.1.7_associations.md @@ -0,0 +1,47 @@ +Updating and creating associations are done in a few different ways in the API +depending on the type of association. + +#### One-to-One and One-to-Many + +To update a one-to-one or a one-to-many association, simply set the name or id +on the object. For example, to set a host group for a host, simply set the +hostgroup_name or hostgroup_id of the host. + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + -H "Content-Type: application/json" -X POST \ + -d '{ "hostgroup_name": "telerin" }' \ + https://foreman.example.com/api/hosts/celeborn.firstage + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + -H "Content-Type: application/json" -X POST \ + -d '{ "hostgroup_id": 42 }' \ + https://foreman.example.com/api/hosts/celeborn.firstage + +#### Many-to-One and Many-to-Many + +To update an association for an object that contains a collection of other +objects, there are a few options. First you can set the names or ids: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + -H "Content-Type: application/json" -X POST \ + -d '{ "host_names": ["enel.first", "celeborni.first", "elwe.first"] }' \ + https://foreman.example.com/api/hostgroups/telerin + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + -H "Content-Type: application/json" -X POST \ + -d '{ "host_ids": [4, 5, 6] }' \ + https://foreman.example.com/api/hostgroups/telerin + +This will set the host group's hosts to enel, celeborn, and elwe (or 4, 5, 6) +and only those. + +Alternatively, you can pass in a set of objects: + + $ curl -k -u admin:changeme -H "Accept: version=2,application/json" \ + -H "Content-Type: application/json" -X POST \ + -d '{ "domains": [{ "name": "earendil", "id": 1}, { "name": "turgon", "id": 3 }] }' \ + https://foreman.example.com/api/subnets/iluvatar + +This would set the domains for the subnet to be earendil and turgon. If another +domain for example belonged to the subnet before the request, it would be +removed. diff --git a/_includes/manuals/3.12/5.1.8_authentication.md b/_includes/manuals/3.12/5.1.8_authentication.md new file mode 100644 index 0000000000..aaa52b015a --- /dev/null +++ b/_includes/manuals/3.12/5.1.8_authentication.md @@ -0,0 +1,39 @@ +The API requires authentication for all endpoints, typically using HTTP Basic authentication. Requests with credentials are authenticated against the users stored in Foreman. + +#### HTTP Basic authentication + +HTTP Basic authentication (RFC 2617) is supported by a wide range of API and web clients and works by specifying a Base64-encoded username and password in an `Authorization` header. For example, these common clients can access the API with the following arguments: + +* `curl -u admin:changeme`, or `curl -u admin` (interactive prompt) +* `wget --user=admin --password=changeme` + +Every call to the API will require authentication, unless the client supports sessions (see below). Some clients may also support storing credentials in `~/.netrc` or similar for more privacy. + +No confidentiality is provided with this method, so it is very important to use HTTPS when connecting to Foreman to prevent the plain-text credentials from being obtained. (Note that when `require_ssl` is enabled, access to the API will only be allowed over HTTPS.) + +#### Session support + +When authenticating to the API, a new server-side session will be created on each request and the response will contain a cookie containing a session ID. If this cookie is stored by the client, it can be used on subsequent requests so the credentials are only passed over the connection once. + +A basic authenticated request to the status API returns the following `Set-Cookie` header, containing a `_session_id` cookie: + + > GET /api/v2/status HTTP/1.1 + > Authorization: Basic YWRtaW46Y2hhbmdlbWU= + > Host: foreman.example.com + > Accept: */* + + < HTTP/1.1 200 OK + < ... + < Set-Cookie: _session_id=572ca37e8c5845b900cc58d45d6e1e34; path=/; secure; HttpOnly + +When supplying this on subsequent requests, they will use the same account: + + > GET /api/v2/status HTTP/1.1 + > Host: foreman.example.com + > Accept: */* + > Cookie: _session_id=572ca37e8c5845b900cc58d45d6e1e34 + + < HTTP/1.1 200 OK + < ... + +Command-line clients may support cookie jars for automatic storage of cookies, e.g. `curl -c ~/.foreman_cookies -b ~/.foreman_cookies` will automatically store and use cookies. diff --git a/_includes/manuals/3.12/5.1.9_oauth.md b/_includes/manuals/3.12/5.1.9_oauth.md new file mode 100644 index 0000000000..7d6dad1965 --- /dev/null +++ b/_includes/manuals/3.12/5.1.9_oauth.md @@ -0,0 +1,34 @@ +Alternatively to basic authentication, limited OAuth 1.0 authentication is supported +in the API. + +#### Configuration of OAuth in Foreman + +OAuth must be enabled in Foreman settings. In *Administer > Settings > Authentication*, +search for *OAuth active* configuration and set it to *Yes*. Then set *OAuth consumer key* +to some string. This will be a token used by all OAuth clients. + +If you want all API requests made using OAuth to be authorized as built-in anonymous +admin user keep *OAuth map users* set to *No*. If you want to specify the user +under which the request is made, change this configuration option to *Yes*. This +allows client to send FOREMAN-USER header with the login of existing Foreman user. +Please note that this header is not signed in OAuth request so can be forged. +Anyone with valid consumer key can impersonate any Foreman user. + +#### Request example + +Usually some OAuth client library is used to generate the request. An example of +curl command can be found here to better understand how it works + + $ curl 'https://foreman.example.com/api/architectures' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json,version=2' \ + -H 'FOREMAN-USER: ares' \ + -H 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="secretkey",oauth_signature_method="hmac-sha1",oauth_timestamp=1321473112,oauth_signature=Il8hR8/ogj/XVuOqMPB9qNjSy6E=' + +In example above we list architectures using OAuth for authentication. We try to +do the request under user with login *ares*, if mapping is enabled on Foreman side, +the result will only include architectures, that user *ares* can see. Note that we +constructed the signature manually, this should change with any oauth_timestamp +change. Also it reflects every parameter, HTTP method and URI change. Therefore +we recommend using some OAuth client library that will construct all OAuth +parameters. diff --git a/_includes/manuals/3.12/5.1_api.md b/_includes/manuals/3.12/5.1_api.md new file mode 100644 index 0000000000..18749fd1a4 --- /dev/null +++ b/_includes/manuals/3.12/5.1_api.md @@ -0,0 +1,3 @@ +[API v2](api/{{page.version}}/index.html) is the default, stable and recommended version for Foreman {{page.version}}. Foreman 1.22 and above also provides a [GraphQL](https://graphql.org/) API. This API is considered experimental for now. Please test it and provide feedback, we do not recommend it for production use just yet. + +This section documents the JSON API conventions for the Foreman API v2 and Katello API v2. To explicitly select the API version, see [Section 5.1.6](manuals/{{page.version}}/index.html#5.1.6APIVersioning). diff --git a/_includes/manuals/3.12/5.2.1_cr_using.md b/_includes/manuals/3.12/5.2.1_cr_using.md new file mode 100644 index 0000000000..3a857d8fd0 --- /dev/null +++ b/_includes/manuals/3.12/5.2.1_cr_using.md @@ -0,0 +1,22 @@ + +The following steps describe how to configure a compute resource and provision new hosts on it. + +1. Ensure the necessary package for the provider (from the above table) is installed, e.g. `yum -y install foreman-ovirt`. Restart the Foreman application to complete installation. + +1. Add a compute resource under *Infrastructure > Compute Resources > New Compute Resource*. Select the provider type from the menu and appropriate configuration options will be displayed. Check the notes sections below for any provider-specific setup instructions. + +1. Click the *Test Connection* button after entering the configuration. If no error is displayed, the test was successful. + +1. After saving the compute resource, existing virtual machines can be browsed by clicking on the compute resource and the *Virtual Machines* tab. + +1. For providers that use images, click on the compute resource, then the *Images* tab, where known images are listed. To register images that Foreman can use, click *New Image* and enter the details. + +1. To provision a new host on this compute resource, from *Hosts*, click *New Host* and select the compute resource from the *Deploy to* menu. + +Also note the following features: + +1. When viewing a host, power management controls and the console access button are in the top right hand corner of the page. + +1. If a host provisioned on a compute resource is deleted, the VM and associated storage on the compute resource will also be deleted. + +1. Users in Foreman can have access restricted to hosts present on certain compute resources. For more information, see Filtering in [4.1.2 Roles and Permissions](/manuals/{{page.version}}/index.html#4.1.2RolesandPermissions). diff --git a/_includes/manuals/3.12/5.2.2_cr_profiles.md b/_includes/manuals/3.12/5.2.2_cr_profiles.md new file mode 100644 index 0000000000..063c51833c --- /dev/null +++ b/_includes/manuals/3.12/5.2.2_cr_profiles.md @@ -0,0 +1,78 @@ + +A compute profile is a way of expressing a set of defaults for VMs created on a +specific compute resource that can be mapped to an operator-defined label. This +means an administrator can express, for example, what "Small", Medium" or +"Large" means on all of the individual compute resources present for a given +installation. + +In combination with host groups, this allows a user to completely define a new +host from just the *Host* tab of the *New Host* form. + +You can find the configuration for compute profiles at *Infrastructure > +Compute Profiles* + +#### Default Profiles + +By default, Foreman comes with 3 predefined profiles; "1-Small", "2-Medium", +and "3-Large" (the numbers are just to make them sort nicely). They come with +no associated configuration for any particular compute resource, and as such, +they can be deleted or renamed as required. + +![Profile List](/static/images/screenshots/compute_profiles/profile-list.png) + +#### Assigning information to a Profile + +This walkthrough will define what "1-Small" means for a particular +installation. It will also assume there are two compute resources; one Libvirt +and one EC2 (these make a good example as they are very different). + +Start by editing the compute profile, by clicking its name in the profile +list. This leads to a list of all your current compute resources. Later, +once the configuration is done, this list will also display the current +defaults configured for each compute resource. + +![Profile Edit](/static/images/screenshots/compute_profiles/profile-edit.png) + +##### EC2 + +Clicking on the EC2 resource will bring up a page very similar to the one used +when provisioning a single host. Here an administrator can set what "1-Small" +means on this specific EC2 resource. For this example, "m1.small" is selected +as the size. Defaults can also be specified for the image choice, the security +groups, and so on. + +![EC2](/static/images/screenshots/compute_profiles/ec2.png) + +The changes are submitted, and on returning to the profile list, the new EC2 +defaults will be shown. + +##### Libvirt + +In a very similar manner, the Libvirt resource can be clicked upon, and some +defaults assigned. For this example, since this is the "1-Small" profile, 1 +CPU, 512MB of RAM, a single bridged network device, and a 5GB disk are +selected. + +![Libvirt](/static/images/screenshots/compute_profiles/libvirt.png) + +Again, the changes are submitted. + +#### Applying a Compute Profile + +Now visit *Hosts > New Host*. At first, things look exactly as before, but once +a compute resource is selected which has at least one compute profile, a new +combo-box will appear. This permits the user to select a profile to apply to +this host. For this example, the Libvirt resource is selected, followed by the +"1-Small" profile. + +![Primary Tab](/static/images/screenshots/compute_profiles/host-primary.png) + +Once the profile is selected, the *Virtual Machine* tab will automatically +update to use the defaults configured in the "1-Small" profile. + +![VM Tab](/static/images/screenshots/compute_profiles/host-vm.png) + +Assuming the defaults are suitable, the host has now been defined solely by +selecting a host group and a profile. It's also possible to associate a profile +with a host group in the host group edit page, which will automatically select +that profile when the host group is selected. diff --git a/_includes/manuals/3.12/5.2.3_cr_ec2.md b/_includes/manuals/3.12/5.2.3_cr_ec2.md new file mode 100644 index 0000000000..4db48b4de4 --- /dev/null +++ b/_includes/manuals/3.12/5.2.3_cr_ec2.md @@ -0,0 +1,13 @@ + +* Add a provisioning template of either type *finish* or *user_data* which will be executed on the new image. + * 'finish' templates complete the provisioning process via SSH - this requires Foreman to be able to reach the IP of the new host, and that SSH is allowing connections from Foreman. This uses the SSH key which Foreman uploaded to your compute resource when it was added to Foreman. + * 'user_data' templates instead provision by cloud-init (or similar meta-data retrieving scripts). This will not require Foreman to be able to reach the host, but the host must be able to reach Foreman (since user_data execution is asynchronous, the host must notify Foreman that the build is complete). +* Ensure AMIs are added under the *Images* tab on the compute resource + * Ensure the correct username is set for Foreman to SSH into the image (if using SSH provisioning). + * Tick the user_data box if the image is capable of using user_data scripts (usually because it has cloud-init installed). +* Enabling *use_uuid_for_certificates* in *Administer > Settings* is recommended for consistent Puppet certificate IDs instead of hostnames. +* VPC subnets and security groups can be selected on the *Network* tab when creating a host. +* The *Managed IP* dropdown menu allows selection between using the public and private IP address for communication from Foreman to the instance. +* Ensure that the selected template is associated to the OS (on the *Associations* tab) and is set as the default for the operating system too. + +A finish-based example for configuring EC2 provisioning is given on the Foreman blog: [EC2 provisioning using Foreman](/2012/05/ec2-provisioning-using-foreman.html). diff --git a/_includes/manuals/3.12/5.2.4_cr_gce.md b/_includes/manuals/3.12/5.2.4_cr_gce.md new file mode 100644 index 0000000000..c8167e2e89 --- /dev/null +++ b/_includes/manuals/3.12/5.2.4_cr_gce.md @@ -0,0 +1,48 @@ +* Requires client e-mail address of an authorised Google Cloud Console client ID is entered in the new compute resource screen and its associated .json private key file is manually transferred to the foreman server. +* The certificate must be stored in a location the foreman user account has permission to read. +* If your server enforces SELinux ensure the context is suitable or relabel it using `restorecon -vv /usr/share/foreman/gce.json` +* Specify the location *on the foreman server* as the certificate path value e.g /usr/share/foreman/gce.json +* Ensure images are associated under the *Images* tab on the compute resource + * Ensure the correct username except *root* is set for Foreman to SSH into the image (if using SSH provisioning). Note that - For security reasons, Google do not provide the ability to ssh in directly as root. + * Tick the user_data box if the image is capable of using user_data scripts (usually because it has cloud-init installed). +* Add a provisioning template either of type *finish* or *user_data* which will be executed on the new image. + * 'finish' templates complete the provisioning process via SSH - this requires Foreman to be able to reach the IP of the new host, and that SSH is allowing connections from Foreman. This uses the SSH key which Foreman uploaded to your compute resource when it was added to Foreman. + * 'user_data' templates instead provision by cloud-init (or similar meta-data retrieving scripts). This will not require Foreman to be able to reach the host, but the host must be able to reach Foreman (since user_data execution is asynchronous, the host must notify Foreman that the build is complete). +* Enabling *use_uuid_for_certificates* in *Administer > Settings* is recommended for consistent Puppet certificate IDs instead of hostnames. +* The *Associate Ephemeral External IP* checkbox means the public IP address (rather than private IP) will be used for communication with the instance from Foreman. +* Ensure that the selected template is associated to the OS (on the *Associations* tab) and is set as the default for the operating system too. + +#### Setting up the cloud project + +All Google Compute Engine access is contained within a "project" set up via the Google Developers Console. Access [the Google Developers Console](https://console.developers.google.com/iam-admin/projects), and click *Create Project*. + +![Create Project](/static/images/screenshots/gce/new_create_project.png) + +By default, your project will have the Compute Engine and App Engine services enabled. +Now go to [the Compute Engine API Overiew](https://console.developers.google.com/apis/api/compute_component), and select the Google Compute Engine API. + +![Compute Engine API Overiew](/static/images/screenshots/gce/enabled_compute_engine_api.png) + +Under *APIs &amp; Services > Library*, apply filter *compute* and select *API* then click the *Enable* button. + +![API Library](/static/images/screenshots/gce/api_library.png) + +![Enable API](/static/images/screenshots/gce/new_enable_api.png) + +Next under *Credentials*, click *Create Credentials > Create service account key* and choose your service account for Compute Engine. + +![Credential list](/static/images/screenshots/gce/credential_list.png) + +![Service account](/static/images/screenshots/gce/create_credentials_using_json_format.png) + +Click *Generate new JSON key* and save the new .json file. This should be uploaded to the Foreman server to a location that the 'foreman' user can read, such as `/usr/share/foreman/gce.json`. You don't need to provide any password to Foreman to use this JSON key. + +<div class="alert alert-info">Change the .json file owner to 'foreman' and chmod 0600 for security. If your server uses SELinux ensure the context is suitable or relabel it using restorecon -vv /usr/share/foreman/gce.json</div> + +#### Adding the compute resource + +In Foreman, under *Infrastructure > Compute resources > New compute resource*, select *Google* from the provider dropdown menu and fill in the GCE-specific fields as follows: + +* *Google Project ID:* shown on the project overview page in the GCE console, e.g. "nomadic-rite-396" +* *Client Email:* shown on the [*Credentials* page](https://console.developers.google.com/iam-admin/serviceaccounts/) after creating the service account as *Service account ID*, e.g. "543...@developer.gserviceaccount.com" +* *Certificate path:* full path of the .json file stored on the Foreman server, e.g. /usr/share/foreman/gce.json diff --git a/_includes/manuals/3.12/5.2.5_cr_libvirt.md b/_includes/manuals/3.12/5.2.5_cr_libvirt.md new file mode 100644 index 0000000000..cf1b9dad0c --- /dev/null +++ b/_includes/manuals/3.12/5.2.5_cr_libvirt.md @@ -0,0 +1,76 @@ + +* Currently only supports KVM hypervisors. +* VM consoles will be configured by default to listen on 0.0.0.0, change this via *libvirt_default_console_address* in *Administer > Settings > Provisioning*. +* libvirt's DNS and DHCP server (dnsmasq) can be disabled and replaced by BIND and ISC DHCPD (managed by Foreman) by creating a new virtual network and disabling DHCP support. + +#### Connections + +To connect to the hypervisor using SSH: + +1. Configure SSH keys (ssh-keygen) for the 'foreman' user on the Foreman host to connect fully automatically to the remote hypervisor host. +1. Change to the 'foreman' user, test the connection and ensure the remote host has been trusted. +1. If connecting to the hypervisor as a non-root user, set up PolicyKit to permit access to libvirt. Note that different versions of PolicyKit have different configuration formats. [1](http://libvirt.org/auth.html#ACL_server_polkit), [2](http://wiki.libvirt.org/page/SSHPolicyKitSetup). +1. Add the compute resource with a URL following one of these examples: + * `qemu+ssh://root@hypervisor.example.com/system` to use the remote 'root' account + * `qemu+ssh://hypervisor.example.com/system` to use the remote 'foreman' account + +The first two steps above can be done with something like: + + root# mkdir /usr/share/foreman/.ssh + root# chmod 700 /usr/share/foreman/.ssh + root# chown foreman:foreman /usr/share/foreman/.ssh + +When using distribution packages, the directory should already be created for +you so you could skip the above. Although following is necessary: + + root# su foreman -s /bin/bash + foreman$ ssh-keygen + foreman$ ssh-copy-id root@hostname.com + foreman$ ssh root@hostname.com + exit + +When using SELinux make sure the directory and the files have correct labels +of `ssh_home_t`: + + ls /usr/share/foreman/.ssh -Zd + drwx------. foreman foreman system_u:object_r:ssh_home_t:s0 /usr/share/foreman/.ssh + ls /usr/share/foreman/.ssh -Z + -rw-------. foreman foreman unconfined_u:object_r:ssh_home_t:s0 id_rsa + -rw-r--r--. foreman foreman unconfined_u:object_r:ssh_home_t:s0 id_rsa.pub + -rw-r--r--. foreman foreman unconfined_u:object_r:ssh_home_t:s0 known_hosts + +If not, restore the context: + + restorecon -RvF /usr/share/foreman/.ssh + +To connect to the hypervisor over TCP without authentication or encryption (not recommended): + +1. Set the following options in libvirtd.conf: + * `listen_tls = 0` + * `listen_tcp = 1` + * `auth_tcp = "none"` +1. Enable libvirtd listening, e.g. set `LIBVIRTD_ARGS="--listen"` in /etc/sysconfig/libvirtd +1. Add the compute resource with a URL following this example: + * `qemu+tcp://hypervisor.example.com:16509/system` + +If you have difficulty connecting, test access using the virsh command under the 'foreman' account on the Foreman host first, e.g. `virsh -c qemu+ssh://hypervisor.example.com/system list`. + +#### Image provisioning + +Image based provisioning can be used by provisioning a VM with a backing image and then running a finish script over SSH, in the same manner as the EC2 provider. The type of provisioning method can be selected under the "Operating system" tab when creating a new host. To configure image/template-based provisioning: + +* Images refer to backing disks (usually qcow2) - create a disk containing the OS image in the libvirt storage pool. +* Add the image by navigating to the compute resource and clicking *New Image*, enter the full path to the backing image in the *Image path* field. +* Ensure the image is not modified as long as hosts exists that are using it, or they will suffer data corruption. + +Two methods to complete provisioning are supported. Either by SSHing into the newly created VM and running a script: + +* The template needs to have a username and password set up for Foreman to SSH in after provisioning and run the finish script. +* This requires some form of DHCP orchestration for SSH access to the newly created host to work. +* A finish template to perform any post-build actions (e.g. setting up Puppet) must also be associated to the host, usually by changing the OS default finish template. + +Or select the userdata checkbox when adding the image to Foreman, and a cloud-init compatible disk will be attached to the VM containing the userdata: + +* The template will need cloud-init installed and set to run on boot. +* A userdata template to perform any post-build actions (e.g. setting up Puppet) must also be associated to the host, usually by associating the `UserData default` template. +* The template will need to "phone home" to mark the host as built. diff --git a/_includes/manuals/3.12/5.2.6_cr_openstack.md b/_includes/manuals/3.12/5.2.6_cr_openstack.md new file mode 100644 index 0000000000..5b63888763 --- /dev/null +++ b/_includes/manuals/3.12/5.2.6_cr_openstack.md @@ -0,0 +1,13 @@ + +* Supports OpenStack Nova for creating new compute instances. +* Add a provisioning template of either type *finish* or *user_data* which will be executed on the new image. + * 'finish' templates complete the provisioning process via SSH - this requires Foreman to be able to reach the IP of the new host, and that SSH is allowing connections from Foreman. This uses the SSH key which Foreman uploaded to your compute resource when it was added to Foreman. + * 'user_data' templates instead provision by cloud-init (or similar meta-data retrieving scripts). This will not require Foreman to be able to reach the host, but the host must be able to reach Foreman (since user_data execution is asynchronous, the host must notify Foreman that the build is complete). +* Ensure Glance Images are added under the *Images* tab on the compute resource. + * Ensure the correct username is set for Foreman to SSH into the image (if using SSH provisioning). + * Tick the user_data box if the image is capable of using user_data scripts (usually because it has cloud-init installed). +* Security groups can be selected on the *Virtual Machine* tab when creating a host. +* The *Floating IP Network* dropdown menu allows selection of the network Foreman should request a public IP on. This is required when using SSH provisioning. +* Ensure that the selected template is associated to the OS (on the *Associations* tab) and is set as the default for the operating system too. + +A finish-based example for configuring image-based provisioning is given on the Foreman blog, also applicable to OpenStack: [EC2 provisioning using Foreman](/2012/05/ec2-provisioning-using-foreman.html). diff --git a/_includes/manuals/3.12/5.2.7_cr_ovirt.md b/_includes/manuals/3.12/5.2.7_cr_ovirt.md new file mode 100644 index 0000000000..e40992ee8d --- /dev/null +++ b/_includes/manuals/3.12/5.2.7_cr_ovirt.md @@ -0,0 +1,44 @@ + +* SPICE consoles are displayed using an HTML5 client, so no native XPI extension is necessary. + +#### Image provisioning + +Image based provisioning can be used by provisioning a VM with a template and then running a finish script over SSH, in the same manner as the EC2 provider. The type of provisioning method can be selected under the "Operating system" tab when creating a new host. To configure image/template-based provisioning: + +* Images refer to templates and can be added by navigating to the compute resource and clicking *New Image*. +* The template needs to have a username and password set up for Foreman to SSH in after provisioning and run the finish script. +* This requires some form of DHCP orchestration for SSH access to the newly created host to work. +* A finish template to perform any post-build actions (e.g. setting up Puppet) must also be associated to the host, usually by changing the OS default finish template. + +#### Permissions required + +When defining a compute resource you have to provide a user account used for communication with oVirt. It must have Admin account type role(s) with following permissions: + +* System + * Configure System + * Login Pemissions + +* Network + * Configure vNIC Profile + * Create + * Edit Properties + * Delete + * Assign vNIC Profile to VM + * Assign vNIC Profile to Template + +* Template + * Provisioning Operations + * Import/Export + +* VM + * Provisioning Operations + * Create + * Delete + * Import/Export + * Edit Storage + +* Disk + * Provisioning Operations + * Create + * Disk Profile + * Attach Disk Profile diff --git a/_includes/manuals/3.12/5.2.8_cr_vmware.md b/_includes/manuals/3.12/5.2.8_cr_vmware.md new file mode 100644 index 0000000000..fcb79a736b --- /dev/null +++ b/_includes/manuals/3.12/5.2.8_cr_vmware.md @@ -0,0 +1,102 @@ +* Only VMware clusters using vSphere are supported, not standalone ESX or ESXi servers ([#1945](http://projects.theforeman.org/issues/1945)). + +#### Image provisioning + +Image based provisioning can be used by provisioning a new VM from a template and then running a finish script over SSH, in the same manner as the EC2 provider. The type of provisioning method can be selected under the "Operating system" tab when creating a new host. To configure image/template-based provisioning: + +* Images refer to templates stored in vSphere which will be used as the basis for a new VM. +* Add the image by navigating to the compute resource and clicking *New Image*, enter the relative path and name of the template on the vSphere server, e.g. `My templates/RHEL 6` or `RHEL 6` if it isn't in a folder. Do not include the datacenter name. +* The template needs to have a username and password set up for Foreman to SSH in after provisioning and run the finish script. +* This requires some form of DHCP orchestration for SSH access to the newly created host to work. +* A finish template to perform any post-build actions (e.g. setting up Puppet) must also be associated to the host, usually by changing the OS default finish template. + +#### Image provisioning without SSH + +The same process can also be done using a user_data template. To configure image/template-based provisioning without SSH, make the following adjustments for the former procedure: + +* Browse then to the image to be used for provisioning, and ensure that "User Data" is checked +* Associate a user_data template to the host. The template will use cloud-init syntax. +* Note that the images don't need cloudinit installed, as the cloudinit is converted under the hood to a CustomisationSpec object that VMware can process + +#### Console access + +Consoles are provided using VNC connections from Foreman to the ESX server, which requires a firewall change to open the respective ports (TCP 5901 to 5964) + +{% highlight bash %} +ssh root@esx-srv +vi /etc/vmware/firewall/vnc.xml +{% endhighlight %} + +Add the following file content: + +{% highlight xml %} +<ConfigRoot> +<service id='0032'> + <id>VNC</id> + <rule id = '0000'> + <direction>inbound</direction> + <protocol>tcp</protocol> + <porttype>dst</porttype> + <port> + <begin>5901</begin> + <end>5964</end> + </port> + </rule> + <enabled>true</enabled> +</service> +</ConfigRoot> +{% endhighlight %} + +Apply and check the firewall rule: + +{% highlight bash %} +esxcli network firewall refresh +esxcli network firewall ruleset list | grep VNC +{% endhighlight %} + +Lastly, make the rule persistent. + +With ESX: + +{% highlight bash %} +cp /etc/vmware/firewall/vnc.xml /vmfs/volumes/datastore1/vnc.xml +vi /etc/rc.local +# At end of file : +cp /vmfs/volumes/datastore1/vnc.xml /etc/vmware/firewall/ +esxcli network firewall refresh +{% endhighlight %} + +With ESXi: + +{% highlight bash %} +cp /etc/vmware/firewall/vnc.xml /vmfs/volumes/datastore1/vnc.xml +vi /etc/rc.local.d/local.sh +# At end of file, just before exit 0 : +cp /vmfs/volumes/datastore1/vnc.xml /etc/vmware/firewall/ +esxcli network firewall refresh +{% endhighlight %} + +If permanent shared storage is available (direct-attach SAN, etc): rather than doing a file copy on each server, use a symlink instead. Once it's changed on the shared storage, run a loop to refresh the firewall services. The local.sh file still needs to be created. + +Example: + +{% highlight bash %} +ln -s /vmfs/volumes/{uuid of shared storage}/firewall.rules/vnc.xml /etc/vmware/firewall/vnc.xml +{% endhighlight %} + +#### Required Permissions +The minimum permissions to properly provision new virtual machines are: + +* All Privileges -> Datastore -> Allocate Space +* All Privileges -> Network -> Assign Network +* All Privileges -> Resource -> Assign virtual machine to resource pool +* All Privileges -> Virtual Machine -> Configuration (All) +* All Privileges -> Virtual Machine -> Interaction +* All Privileges -> Virtual Machine -> Inventory +* All Privileges -> Virtual Machine -> Provisioning + +#### Notes +* Log in to the VMware vSphere Server that represents the Compute Resource. Create a role with the above permissions. Add the appropriate account to the role. To create user accounts, roles or for complete details on administration of VMware vSphere, please consult your VMware vSphere Server documentation. +* The account that foreman uses to communicate with VCenter is assumed to have the ability to traverse the entire inventory in order to locate a given datacenter. A patch is required to instruct foreman to navigate directly to the appropriate datacenter to avoid permission issues ([#5006](http://projects.theforeman.org/issues/5006)). +* Reference in the [VMWare KB 2043564](http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&docType=kc&externalId=2043564&sliceId=1&docTypeID=DT_KB_1_1&dialogID=458724081&stateId=1%200%20458722496). +* For debugging purpose, read the [troubleshooting guide about NoVNC](/manuals/{{page.version}}/index.html#7.1NoVNC). diff --git a/_includes/manuals/3.12/5.2.9_cr_encryption_key.md b/_includes/manuals/3.12/5.2.9_cr_encryption_key.md new file mode 100644 index 0000000000..101d3f7980 --- /dev/null +++ b/_includes/manuals/3.12/5.2.9_cr_encryption_key.md @@ -0,0 +1,9 @@ +Compute resource passwords and secrets are stored on the Foreman database using a secret - the encryption key - and ciphered using AES-256-CBC. +The encryption key can usually be found in `/etc/foreman/encryption_key.rb`, which is symlinked to `/usr/share/foreman/config/initializers/encryption_key.rb`. The value of the ENCRYPTION_KEY variable must be at least 32 bytes long. + +If you want to regenerate the key, you can run `foreman-rake security:generate_encryption_key`. Please remember that previously encrypted passwords cannot be decrypted with a different encryption key, so decrypt all passwords before changing your encryption key. + +After you make sure you have a valid encryption key, you can encrypt your Compute Resource secrets in the database by running `foreman-rake db:compute_resources:encrypt`. +To unencrypt them, run the task `foreman-rake db:compute_resources:decrypt`. + +Keep in mind passwords are encrypted in the Foreman database, but Foreman will decrypt them and use unencrypted credentials to authenticate to Compute Resources. diff --git a/_includes/manuals/3.12/5.2_compute_resources.md b/_includes/manuals/3.12/5.2_compute_resources.md new file mode 100644 index 0000000000..5d76808c64 --- /dev/null +++ b/_includes/manuals/3.12/5.2_compute_resources.md @@ -0,0 +1,74 @@ + +Foreman supports creating and managing hosts on a number of virtualization and cloud services - referred to as "compute resources" - as well as bare metal hosts. + +The capabilities vary between implementations, depending on how the compute resource provider deploys new hosts and what features are available to manage currently running hosts. Some providers are able to support unattended installation using PXE, while others are image-based. Some providers have graphical consoles that Foreman interfaces to, and most have power management features. A summary of all providers and their support features is given below, and more detailed sections follow with specific notes. + +<table class="table table-bordered table-condensed"> + <tr> + <th>Provider</th> + <th>Package</th> + <th>Unattended installation</th> + <th>Image-based</th> + <th>Console</th> + <th>Power management</th> + <th>Networking</th> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.3EC2Notes">EC2</a></td> + <td>foreman-ec2</td> + <td>no</td> + <td>yes</td> + <td>read-only</td> + <td>yes</td> + <td>IPv4</td> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.4GoogleComputeEngineNotes">Google Compute Engine</a></td> + <td>foreman-plugin-google</td> + <td>no</td> + <td>yes</td> + <td>read-only</td> + <td>yes</td> + <td>IPv4</td> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.5LibvirtNotes">Libvirt</a></td> + <td>foreman-libvirt</td> + <td>yes</td> + <td>yes</td> + <td>VNC or SPICE</td> + <td>yes</td> + <td>MAC</td> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.6OpenStackNotes">OpenStack Nova</a></td> + <td>foreman-openstack</td> + <td>no</td> + <td>yes</td> + <td>no</td> + <td>yes</td> + <td>IPv4</td> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.7oVirt/RHEVNotes">oVirt / RHEV</a></td> + <td>foreman-ovirt</td> + <td>yes</td> + <td>yes</td> + <td>VNC or SPICE</td> + <td>yes</td> + <td>MAC</td> + </tr> + <tr> + <td><a href="/manuals/{{page.version}}/index.html#5.2.8VMwareNotes">VMware</a></td> + <td>foreman-vmware</td> + <td>yes</td> + <td>yes</td> + <td>VNC</td> + <td>yes</td> + <td>MAC</td> + </tr> +</table> + +Support for these features is aimed at being as transparent as possible, allowing the same configuration to be applied to hosts irrespective of the provider in use (compute resource or not). The selection of compute resource is made when creating a new host and the host in Foreman's database remains associated to the VM that's created, allowing it to be managed throughout the lifetime of the host. + +Networking varies between providers - where "MAC" is specified, the compute resource provides the MAC address for newly created virtual machines (layer 2 networking), and IP addresses are assigned in/by Foreman. Where "IPv4" and/or "IPv6" is specified, the compute resource assigns an IP address for virtual machine interfaces (layer 3 networking) and the addresses will be stored by Foreman when creating a host. diff --git a/_includes/manuals/3.12/5.4.1_comms_puppetserver.md b/_includes/manuals/3.12/5.4.1_comms_puppetserver.md new file mode 100644 index 0000000000..5cf50feee2 --- /dev/null +++ b/_includes/manuals/3.12/5.4.1_comms_puppetserver.md @@ -0,0 +1,67 @@ + +In a typical ENC-based setup with reporting, Puppet servers require access to Foreman for three tasks: + +1. Retrieval of external nodes information (classes, parameters) +2. Uploading of host facts +3. Uploading of host reports + +All traffic here is initiated by the Puppet server itself. Other traffic from Foreman to the Puppet server for certificate signing etc. is handled via smart proxies (SSL configuration covered in the next section). + +#### Configuration options + +The Foreman interface authorizes access to Puppet server interfaces based on its list of registered smart proxies with the *Puppet* feature, and identifies hosts using client SSL certificates. + +Five main settings control the authentication, the first are in Foreman under *Settings*, *Authentication*: + +* *require_ssl_smart_proxies* (default: true), requires a client SSL certificate on the Puppet server requests, and will verify the CN of the certificate against the smart proxies. If false, it uses the reverse DNS of the IP address making the request. +* *restrict_registered_smart_proxies* (default: true), only permits access to hosts that have a registered smart proxy with the *Puppet* feature. +* *trusted_hosts*, a whitelist of hosts that overrides the check for a registered smart proxy + +And two in `config/settings.yaml`: + +* *login* (default: true), must be enabled to prevent anonymous access to Foreman. +* *require_ssl* (default: false), should be enabled to require SSL for all communications, which in turn will require client SSL certificates if *require_ssl_smart_proxies* is also enabled. If false, host-based access controls will be available for HTTP requests. + +#### Enabling full SSL communications + +Using Apache HTTP with mod_ssl is recommended. For simple setups, the Puppet certificate authority (CA) can be used, with Foreman and other hosts using certificates generated by `puppet cert`. + +1. Set Foreman's *require_ssl_smart_proxies*, *restrict_registered_smart_proxies* and *require_ssl* to _true_. +2. The mod_ssl configuration must contain: + <ol><li>*SSLCACertificateFile* set to the Puppet CA</li> + <li>*SSLVerifyClient optional*</li> + <li>*SSLOptions +StdEnvVars +ExportCertData*</li></ol> +3. Puppet ENC/report processor configuration (e.g. `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml`) should have these settings: + <ol><li>*:ssl_ca* set to the Puppet CA</li> + <li>*:ssl_cert* set to the Puppet server's certificate</li> + <li>*:ssl_key* set to the Puppet server's private key</li></ol> + +##### Troubleshooting + +Warning messages will be printed to Foreman's log file (typically `/var/log/foreman/production.log`) when SSL-based authentication fails. + +* _No SSL cert with CN supplied_ indicates no client SSL certificate was supplied, or the CN wasn't present on a certificate. Check the client script has the certificate and key configured and that mod_ssl has *SSLVerifyClient* set. +* _SSL cert has not been verified_ indicates the client SSL certificate didn't validate with the SSL terminator's certificate authority. Check the client SSL certificate is signed by the CA set in mod_ssl's *SSLCACertificateFile* and is still valid. More information might be in error logs. +* _SSL is required_ indicates the client is using an HTTP URL instead of HTTPS. +* _No smart proxy server found on $HOST_ indicates Foreman has no smart proxy registered for the source host, add it to the Smart Proxies page in Foreman. A common cause of this issue is the hostname in the URL doesn't match the hostname seen here in the log file - change the registered proxy URL to match. If no smart proxy is available or can be installed, use *trusted_hosts* and add this hostname to the whitelist. + +##### Advanced SSL notes + +A typical small setup will use a single Puppet CA and certificates it provides for the Foreman host and Puppet server hosts. In larger setups with multiple CAs or an internal CA, this will require more careful configuration to ensure all hosts can trust each other. + +* Ensure the Common Name (CN) is present in certificates used by Foreman (as clients will validate it) and Puppet server clients (used to verify against smart proxies). +* Foreman's SSL terminator must be able to validate Puppet server client SSL certificates. In Apache with mod_ssl, the *SSLCACertificateFile* option must point to the CA used to validate clients and *SSLVerifyClient* set to _optional_. +* Environment variables from the SSL terminator are used to get the client certificate and verification status. mod_ssl's *SSLOptions +StdEnvVars +ExportCertData* setting enables this. Variable names are defined by *ssl_client_cert_env*, *ssl_client_dn_env* and *ssl_client_verify_env* settings in Foreman. + +#### Reduced security: HTTP host-based authentication + +In non-SSL setups, host-based authentication can be performed, so any connection from a host running a puppet smart proxy is able to access the interfaces. + +1. Set *restrict_registered_smart_proxies* to _true_. +1. Set *require_ssl_smart_proxies* and *require_ssl* to _false_. + +#### No security: disable authentication + +Entirely disabling authentication isn't recommended, since it can lead to security exploits through YAML import interfaces and expose sensitive host information, however it may be useful for troubleshooting. + +1. Set *require_ssl_smart_proxies*, *restrict_registered_smart_proxies* and *require_ssl* to _false_. diff --git a/_includes/manuals/3.12/5.4.2_comms_proxy.md b/_includes/manuals/3.12/5.4.2_comms_proxy.md new file mode 100644 index 0000000000..77e6f1400a --- /dev/null +++ b/_includes/manuals/3.12/5.4.2_comms_proxy.md @@ -0,0 +1,53 @@ + +Foreman makes HTTP requests to smart proxies for a variety of orchestration tasks. In a production setup, these should use SSL certificates so the smart proxy can verify the identity of the Foreman host. + +In a simple setup, a single Puppet Certificate Authority (CA) can be used for authentication between Foreman and proxies. In more advanced setups with multiple CAs or an internal CA, the services can be configured as follows. + +#### Proxy configuration options + +`/etc/foreman-proxy/settings.yml` contains the locations to the SSL certificates and keys: + +```yaml +--- +# SSL Setup + +# if enabled, all communication would be verified via SSL +# NOTE that both certificates need to be signed by the same CA in order for this to work +# see https://theforeman.org/manuals/{{page.version}}/index.html#4.3.10SSL for more information +:ssl_certificate: /etc/puppetlabs/puppet/ssl/certs/FQDN.pem +:ssl_ca_file: /etc/puppetlabs/puppet/ssl/certs/ca.pem +:ssl_private_key: /etc/puppetlabs/puppet/ssl/private_keys/FQDN.pem +``` + +In this example, the proxy is sharing Puppet's certificates, but it could equally use its own. + +In addition it contains a list of hosts that connections will be accepted from, which should be the host(s) running Foreman: + +```yaml +# the hosts which the proxy accepts connections from +# commenting the following lines would mean every verified SSL connection allowed +:trusted_hosts: +- foreman.corp.com +#- foreman.dev.domain +``` + +##### Configuring Foreman + +For Foreman to connect to an SSL-enabled smart proxy, it needs configuring with SSL certificates in the same way. + +The locations of the certificates are managed in the *Settings* page, under *Provisioning* - the _ssl_ca_file_, _ssl_certificate_ and _ssl_priv_key_ settings. By default these will point to the Puppet locations - for manually generated certificates, or non-standard locations, they may have to be changed. + +Lastly, when adding the smart proxy in Foreman, ensure the URL begins with `https://` rather than `http://`. + + +##### Sharing Puppet certificates + +If using Puppet's certificates, the following lines will be required in puppet.conf to relax permissions to the `puppet` group. The `foreman` and/or `foreman-proxy` users should then be added to the `puppet` group. + +```ini +[main] +privatekeydir = $ssldir/private_keys { group = service } +hostprivkey = $privatekeydir/$certname.pem { mode = 640 } +``` + +Note that the "service" keyword will be interpreted by Puppet as the "puppet" service group. diff --git a/_includes/manuals/3.12/5.4_communications.md b/_includes/manuals/3.12/5.4_communications.md new file mode 100644 index 0000000000..e4e25e77bc --- /dev/null +++ b/_includes/manuals/3.12/5.4_communications.md @@ -0,0 +1,2 @@ + +The Foreman web application needs to communicate securely with associated smart proxies and Puppet servers, plus users and applications connecting to the web interface. This section details recommended SSL configurations. diff --git a/_includes/manuals/3.12/5.5.1_backup.md b/_includes/manuals/3.12/5.5.1_backup.md new file mode 100644 index 0000000000..b44608a077 --- /dev/null +++ b/_includes/manuals/3.12/5.5.1_backup.md @@ -0,0 +1,38 @@ + +This chapter will provide you with information how to backup a Foreman +instance. + +#### Database + +Run ```foreman-rake db:dump```. It will print a message when it finishes with the dump file location relative to the Foreman root. + +#### Configuration + +On Red Hat compatible systems issue the following command to backup whole /etc +directory structure: + + tar --selinux -czvf etc_foreman_dir.tar.gz /etc/foreman + +For all other distribution do similar command: + + tar -czvf etc_foreman_dir.tar.gz /etc/foreman + +#### Puppet server + +On the Puppet server node, issue the following command to backup Puppet +certificates on Red Hat compatible systems + + tar --selinux -czvf var_lib_puppet_dir.tar.gz /etc/puppetlabs/puppet/ssl + +For all other distribution do similar command: + + tar -czvf var_lib_puppet_dir.tar.gz /etc/puppetlabs/puppet/ssl + +Under a Puppet non-AIO installation, back up `/var/lib/puppet/ssl` instead. + +#### DHCP, DNS and TFTP services + +Depending on used software packages, perform backup of important data and +configuration files according to the documentation. For ISC DHCP and DNS +software, these are located within /etc and /var directories depending on your +distribution as well as TFTP service. diff --git a/_includes/manuals/3.12/5.5.2_recovery.md b/_includes/manuals/3.12/5.5.2_recovery.md new file mode 100644 index 0000000000..c7190eadd0 --- /dev/null +++ b/_includes/manuals/3.12/5.5.2_recovery.md @@ -0,0 +1,74 @@ + +Recovery process is supposed to be performed on the same host the backup was +created on on the same distribution and version. + +If you planning to *migrate* Foreman instance, please read remarks in the +beginning of this chapter. + +Note: Foreman instance must be stopped before proceeding. + +#### PostgreSQL + +Run ```foreman-rake db:import_dump file=/your/db/dump/location```. This will load your +dump into the current database for your environment. It will print a message +to notify you when it has finished importing the dump. + +Remember to stop the Foreman instance and any other process consuming data from the +database temporarily during the import and turn it back on after it ends. + +#### Configuration + +On Red Hat compatible systems issue the following command to restore whole /etc +directory structure: + + tar --selinux -xzvf etc_foreman_dir.tar.gz -C / + +For all other distribution do similar command: + + tar -xzvf etc_foreman_dir.tar.gz -C / + +It is recommended to extract files to an empty directory first and inspect the +content before overwriting current files (change -C option to an empty +directory). + +#### Puppet server + +On the Puppet server node, issue the following command to restore Puppet +certificates on Red Hat compatible systems + + tar --selinux -xzvf var_lib_puppet_dir.tar.gz -C / + +For all other distribution do similar command: + + tar -xzvf var_lib_puppet_dir.tar.gz -C / + +It is recommended to inspect the content of the restore first (see above). + +#### DHCP, DNS and TFTP services + +Depending on used software packages, perform recovery of important data and +configuration files according to the documentation. This depends on the +software and distribution that is in use. + +#### Changing the FQDN + +It's preferable when migrating to keep the FQDN unchanged to reduce the risk +of configuration errors from references to the old hostname. + +However if the FQDN does change, check and update the following items: + +* [Foreman settings](manuals/{{page.version}}/index.html#3.5.2ConfigurationOptions) under *Administer > Settings*: + * *General > foreman_url* - URL of the Foreman web UI + * *Provisioning > unattended_url* - URL of the Foreman web API for unattended provisioning + * *Provisioning > ssl_certificate*, *ssl_priv_key* - paths to SSL certificate and key used for smart proxy communications +* The registered smart proxy URL if installed, edit via *Infrastructure > Smart Proxies* +* Puppet SSL certs: generate new ones with `puppet cert generate NEW_FQDN` +* Apache configs: update `conf.d/*-{foreman,puppet}.conf` with new SSL cert/key filenames, ServerName and VirtualHost IP addresses if applicable +* Smart proxy configuration files in `/etc/foreman-proxy`: + * `settings.yml` - update SSL cert/key filenames + * `settings.d/dns_nsupdate_gss.yml` - update `dns_tsig_principal` if the principal name has changed + * `settings.d/puppet_proxy_legacy.yml` - update SSL cert/key filenames + * `settings.d/puppet_proxy_puppet_api.yml` - update SSL cert/key filenames + * `settings.d/realm.yml` - update `realm_principal` if the principal name has changed + * `settings.d/templates.yml` - update `template_url` for URL of the Foreman web API +* Puppet servers: URLs and cert/key filenames in `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml` diff --git a/_includes/manuals/3.12/5.5_backup_and_recovery.md b/_includes/manuals/3.12/5.5_backup_and_recovery.md new file mode 100644 index 0000000000..e33ab9de06 --- /dev/null +++ b/_includes/manuals/3.12/5.5_backup_and_recovery.md @@ -0,0 +1,13 @@ + +This chapter will provide you with information how to backup and recover +your instance. All commands presented here are just examples and should be +considered as a template command for your own backup script which differs from +one environment to other. + +It is possible to perform a *migration* by doing backup one one host and +recovery on a different host, but in this case pay attention to different +configuration between the two hosts. + +This can be applied to the Foreman application itself, but pay attention when +migrating smart-proxy and services because things like different IP addresses +or hostnames will need manual intervention. diff --git a/_includes/manuals/3.12/5.6_rails_console.md b/_includes/manuals/3.12/5.6_rails_console.md new file mode 100644 index 0000000000..ba81f8c341 --- /dev/null +++ b/_includes/manuals/3.12/5.6_rails_console.md @@ -0,0 +1,41 @@ + +Foreman is a Ruby on Rails application, which provides an interactive console for advanced debugging and troubleshooting tasks. Using this allows easy bypass of authorization and security mechanisms, and can easily lead to loss of data or corruption unless care is taken. + +To access the Rails console, choose the method below appropriate to the installation method. + +##### RPM and Debian installations + +As root, execute: + +{% highlight bash %} +yum install foreman-console +foreman-rake console +{% endhighlight %} + +or to run in sandboxed mode, which rolls back changes on exit, execute: + +{% highlight bash %} +foreman-rake console -- --sandbox +{% endhighlight %} + +##### Source installations + +As the user running Foreman and in the source directory, execute: + +{% highlight bash %} +RAILS_ENV=production bundle exec rails c +{% endhighlight %} + +or to run in sandboxed mode, which rolls back changes on exit, execute: + +{% highlight bash %} +RAILS_ENV=production bundle exec rails c --sandbox +{% endhighlight %} + +##### Set up + +To assume full admin permissions in order to modify objects, enter in the console: + +{% highlight ruby %} +User.current = User.only_admin.visible.first +{% endhighlight %} diff --git a/_includes/manuals/3.12/5.7.1_quick_configuration.md b/_includes/manuals/3.12/5.7.1_quick_configuration.md new file mode 100644 index 0000000000..24ff5680a8 --- /dev/null +++ b/_includes/manuals/3.12/5.7.1_quick_configuration.md @@ -0,0 +1,24 @@ + +We assume the Foreman machine is FreeIPA-enrolled: +{% highlight bash %} +ipa-client-install +{% endhighlight %} + +On the FreeIPA server, we create the service. +(Please make sure you have obtained Kerberos ticket before this step - for example, by using *kinit*.) +{% highlight bash %} +ipa service-add HTTP/<the-foreman-fqdn> +{% endhighlight %} + +Then we install Foreman. +{% highlight bash %} +foreman-installer --foreman-ipa-authentication=true +{% endhighlight %} +This option can be used for the reconfiguration of existing installation as well. + +In case you want to use IPA server's host-based access control (HBAC) features (make sure *allow_all* rule is disabled), the default PAM service name (which would be matched by HBAC service name) is *foreman*. You can override the default name with: +{% highlight bash %} +foreman-installer --foreman-ipa-authentication=true --foreman-pam-service=<pam_service_name> +{% endhighlight %} + +For more information about HBAC configuration see section below. diff --git a/_includes/manuals/3.12/5.7.2_HBAC_rules.md b/_includes/manuals/3.12/5.7.2_HBAC_rules.md new file mode 100644 index 0000000000..13ba7ed0ac --- /dev/null +++ b/_includes/manuals/3.12/5.7.2_HBAC_rules.md @@ -0,0 +1,28 @@ + +We suppose that the Foreman machine is FreeIPA-enrolled and `HTTP/<the-foreman-fqdn>` service has been created on FreeIPA server. + +At first we create HBAC (host-based access control) service and rule on the FreeIPA server. In the following examples, we will use the PAM service name *foreman-prod*. + +On the FreeIPA server, we define the HBAC service and rule and link them together: + +{% highlight bash %} +ipa hbacsvc-add foreman-prod +ipa hbacrule-add allow_foreman_prod +ipa hbacrule-add-service allow_foreman_prod --hbacsvcs=foreman-prod +{% endhighlight %} + +Then we add user we wish to have access to the service *foreman-prod*, and the hostname of our Foreman server: +{% highlight bash %} +ipa hbacrule-add-user allow_foreman_prod --user=<username> +ipa hbacrule-add-host allow_foreman_prod --hosts=<the-foreman-fqdn> +{% endhighlight %} + +Alternatively, host groups and user groups could be added to the *allow_foreman_prod* rule. + +At any point of the configuration, we can check the status of the rule: +{% highlight bash %} +ipa hbacrule-find foreman-prod +ipa hbactest --user=<username> --host=<the-foreman-fqdn> --service=foreman-prod +{% endhighlight %} + +Chances are there will be HBAC rule *allow_all* matching besides our new *allow_foreman_prod* rule. See http://www.freeipa.org/page/Howto/HBAC_and_allow_all for steps to disable the catchall *allow_all* HBAC rule while maintaining the correct operation of your FreeIPA server and enrolled clients. The goal is only *allow_foreman_prod* matching when checked with `ipa hbactest`. diff --git a/_includes/manuals/3.12/5.7.3_kerberos.md b/_includes/manuals/3.12/5.7.3_kerberos.md new file mode 100644 index 0000000000..d8043c9b6b --- /dev/null +++ b/_includes/manuals/3.12/5.7.3_kerberos.md @@ -0,0 +1,62 @@ +In this part of the tutorial we will show how to set up Foreman authentication manually (without using installer option). + +At first we enroll Foreman machine and define `HTTP/<the-foreman-fqdn>` service in the FreeIPA server. Then we define HBAC service and rules (for more information see the previous section). In the following steps we will use the HBAC service name *foreman-prod*. + +Next step is to define matching PAM service on the Foreman machine. We create file `/etc/pam.d/foreman-prod` with the following content: + +{% highlight bash %} +auth required pam_sss.so +account required pam_sss.so +{% endhighlight %} + +We will also want to enable two SELinux booleans on the Foreman machine: +{% highlight bash %} +setsebool -P allow_httpd_mod_auth_pam on +setsebool -P httpd_dbus_sssd on +{% endhighlight %} + +Get the keytab for the service and set correct permissions (we assume the FreeIPA server is *ipa.example.com*, adjust to match your setup): +{% highlight bash %} +kinit admin +ipa-getkeytab -s $(awk '/^server =/ {print $3}' /etc/ipa/default.conf) -k /etc/http.keytab -p HTTP/$( hostname ) +chown apache /etc/http.keytab +chmod 600 /etc/http.keytab +{% endhighlight %} + +Install mod_auth_gssapi and mod_authnz_pam: +{% highlight bash %} +yum install -y mod_auth_gssapi mod_authnz_pam +{% endhighlight %} + +Configure the module to be used by Apache (we assume the realm is *EXAMPLE.COM*, adjust to match your setup): +{% highlight text %} +# add to /etc/httpd/conf.d/auth_kerb.conf +LoadModule auth_gssapi_module modules/mod_auth_gssapi.so +LoadModule authnz_pam_module modules/mod_authnz_pam.so +<Location /users/extlogin> + AuthType GSSAPI + AuthName "GSSAPI Single Sign On Login" + GssapiCredStore keytab:/etc/http.keytab + GssapiSSLonly On + GssapiLocalName On + # require valid-user + require pam-account foreman-prod + ErrorDocument 401 '<html><meta http-equiv="refresh" content="0; URL=/users/login"><body>Kerberos authentication did not pass.</body></html>' + # The following is needed as a workaround for https://bugzilla.redhat.com/show_bug.cgi?id=1020087 + ErrorDocument 500 '<html><meta http-equiv="refresh" content="0; URL=/users/login"><body>Kerberos authentication did not pass.</body></html>' +</Location> +{% endhighlight %} + +We tell Foreman that it is OK to trust the authentication done by Apache by adding to `/etc/foreman/settings.yaml` or under *Administer > Settings > Authentication*: +{% highlight yaml %} +:authorize_login_delegation: true +{% endhighlight %} + +We restart Apache: +{% highlight bash %} +service httpd restart +{% endhighlight %} + +The machine on which you run the browser to access Foreman's WebUI needs to be either FreeIPA-enrolled to the FreeIPA server or at least configured (typically in `/etc/krb5.conf`) to know about the FreeIPA server Kerberos services. The browser needs to have the Negotiate Authentication enabled; for example in Firefox, in the `about:config` settings, *network.negotiate-auth.trusted-uris* needs to include the Foreman server FQDN or its domain. If you then `kinit` as existing Foreman user to obtain Kerberos ticket-granting ticket, accessing Foreman's WebUI should not ask for login/password and should display the authenticated dashboard directly. + +Please note that we use directive `require pam-account foreman-prod` to also check the access against FreeIPA's HBAC rule. If you do not see Kerberos authentication passing, check that the user is allowed access in FreeIPA (in the section about HBAC configuration we've named the HBAC rule *allow_forman_prod*). diff --git a/_includes/manuals/3.12/5.7.4_pam_authentication.md b/_includes/manuals/3.12/5.7.4_pam_authentication.md new file mode 100644 index 0000000000..d738ecce8f --- /dev/null +++ b/_includes/manuals/3.12/5.7.4_pam_authentication.md @@ -0,0 +1,20 @@ + +The FreeIPA server can be used as an authentication provider for Foreman's standard logon form. We assume the Foreman machine is already FreeIPA-enrolled so sssd is configured to be able to facilitate the authentication, and we have PAM service *foreman-prod* configured. + +We will install the necessary Apache modules: +{% highlight bash %} +yum install -y mod_intercept_form_submit mod_authnz_pam +{% endhighlight %} + +We will then configure Apache to perform PAM authentication (and access control check) using the PAM service *foreman-prod*, for example in configuration file `/etc/httpd/conf.d/intercept_form_submit.conf`: +{% highlight text %} +LoadModule intercept_form_submit_module modules/mod_intercept_form_submit.so +LoadModule authnz_pam_module modules/mod_authnz_pam.so +<Location /users/login> + InterceptFormPAMService foreman-prod + InterceptFormLogin login[login] + InterceptFormPassword login[password] +</Location> +{% endhighlight %} + +After restarting Apache with ``service httpd restart``, you should be able to log in to Foreman's WebUI as existing user, using password from the FreeIPA server. Please note that **intercept_form_submit_module** uses **authnz_pam_module** to run not just the authentication, but access check as well. If the authentication does not pass and you are sure you use the correct password, check also that the user is allowed access in FreeIPA HBAC rules. diff --git a/_includes/manuals/3.12/5.7.5_populate_users_attributes_groups.md b/_includes/manuals/3.12/5.7.5_populate_users_attributes_groups.md new file mode 100644 index 0000000000..662cdd6532 --- /dev/null +++ b/_includes/manuals/3.12/5.7.5_populate_users_attributes_groups.md @@ -0,0 +1,57 @@ + +So far we have tried external authentication for existing Foreman users. + +However, it is also possible to have the user's records in Foreman created automatically, on the fly when they first log in using external authentication (single sign-on, PAM). + +The first step to enable this feature is to add + +:authorize_login_delegation_auth_source_user_autocreate: External + +to `/etc/foreman/settings.yaml` or under *Administer > Settings > Authentication*. + +Since we will want the newly created user records to have valid name and email address, we need to set up **sssd** to provide these attributes and **mod_lookup_identity** to pass them to Foreman. We start by installing the packages: +{% highlight bash %} +yum install -y sssd-dbus mod_lookup_identity +{% endhighlight %} + +Amend the configuration of sssd in `/etc/sssd/sssd.conf`: + +{% highlight text %} +# /etc/sssd/sssd.conf, the [domain/...] section, add: +ldap_user_extra_attrs = email:mail, firstname:givenname, lastname:sn + +# /etc/sssd/sssd.conf, the [sssd] section, amend the services line to include ifp: +services = nss, pam, ssh, ifp + +# /etc/sssd/sssd.conf, add new [ifp] section: +[ifp] +allowed_uids = apache, root +user_attributes = +email, +firstname, +lastname +{% endhighlight %} + +Configure Apache to retrieve these attributes, for example in `/etc/httpd/conf.d/lookup_identity.conf`: +{% highlight text %} +LoadModule lookup_identity_module modules/mod_lookup_identity.so +<LocationMatch ^/users/(ext)?login$> + LookupUserAttr email REMOTE_USER_EMAIL " " + LookupUserAttr firstname REMOTE_USER_FIRSTNAME + LookupUserAttr lastname REMOTE_USER_LASTNAME + LookupUserGroupsIter REMOTE_USER_GROUP +</LocationMatch> +{% endhighlight %} + +Restart both sssd and Apache: +{% highlight bash %} +service sssd restart +service httpd restart +{% endhighlight %} + +Now when you log in either using Kerberos ticket or using user's FreeIPA password (make sure the user has access allowed in FreeIPA HBAC rule), even if the user did not log in to Foreman before, their record will be populated with name and email address from the FreeIPA server (you can check in the top right corner that the full name is there) and they will also be updated upon every subsequent externally-authentication logon. + +You might notice that the newly created user does not have many access right. To fully use the central identity provider like FreeIPA, it can be useful to link group membership of externally-authenticated Foreman users to the group membership of users in FreeIPA, and then set Foreman roles to these user groups. That way when a new network administrator has their record created in FreeIPA with proper user groups and then logs in to Foreman for the first time, their Foreman account will automatically get group memberships in Foreman groups, giving them appropriate roles and access rights. + +The prerequisite is obviously to have the user groups and memberships set appropriately for your organization in FreeIPA. + +For each FreeIPA user group that should have some semantics in Foreman, we create new user groups in Foreman, and then use the tab *External groups* and *Add external user group* to add name of the user group in FreeIPA, for Auth source **EXTERNAL**. We can then assign roles to this Foreman user group to match the desired role for users from the given FreeIPA user group. + +Upon their first login, externally-authenticated users will get their group membership in Foreman set to match the mapping to FreeIPA groups and their group membership in FreeIPA. Upon subsequent externally-authenticated logons, the membership in these mapped groups will be updated to match the current membership in FreeIPA. diff --git a/_includes/manuals/3.12/5.7.6_namespace_separation.md b/_includes/manuals/3.12/5.7.6_namespace_separation.md new file mode 100644 index 0000000000..686bcaa576 --- /dev/null +++ b/_includes/manuals/3.12/5.7.6_namespace_separation.md @@ -0,0 +1,24 @@ + +If clear namespace separation of internally and externally authenticated users is desired, we can distinguish the externally authenticated (and populated) users by having @REALM part in their user names. + +For the Kerberos authentication, using `KrbLocalUserMapping Off` will keep the REALM part of the logon name: +{% highlight text %} +# in /etc/httpd/conf.d/auth_kerb.conf +<Location /users/extlogin> + AuthType Kerberos + ... + KrbLocalUserMapping Off +</Location> +{% endhighlight %} + +For the PAM authentication, using `InterceptFormLoginRealms EXAMPLE.COM` will make the user's login include this @REALM part (even if the +user did not explicitly specify it), thus matching the username seen by Foreman when authenticated via Kerberos ticket: +{% highlight text %} +# in /etc/httpd/conf.d/intercept_form_submit.conf +<Location /users/login> + ... + InterceptFormLoginRealms EXAMPLE.COM +</Location> +{% endhighlight %} + +With this configuration, the @REALM will be part of the username and it would be clear that **bob** is INTERNAL-authenticated and **bob@EXAMPLE.COM** is different user, EXTERNAL-authenticated. The admin then can manually create another **admin@EXAMPLE.COM** user (with administrator privileges) and even the admin can use Kerberos or PAM authentication in this setup. diff --git a/_includes/manuals/3.12/5.7.7_openid_sso.md b/_includes/manuals/3.12/5.7.7_openid_sso.md new file mode 100644 index 0000000000..097ea6126e --- /dev/null +++ b/_includes/manuals/3.12/5.7.7_openid_sso.md @@ -0,0 +1,107 @@ +### Single Sign-on for Foreman using OpenID Connect protocol + +An OpenID Provider(OP) implements a Single Sign-on (SSO) using an OpenID Connect (OIDC) protocol. OIDC verifies the identity of the End-user depending on the given authentication details. In this example, [Keycloak](https://www.keycloak.org/) is used as the OpenID provider, and Foreman is the Relying Party (RP). + +OpenID provider provides an ID Token, encoded in JSON Web Token (JWT) to Foreman. + +An example of an encoded JWT ID Token: + +``` +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` + +#### Configuring Foreman + +As a system administrator, execute the following procedure to configure Foreman. + +Prerequisites + +* A working installation of Foreman at https://foreman.example.com. +* A working installation of OpenID provider, for example, Keycloak at https://keycloak.example.com, which uses the OIDC protocol. Ensure that the Keycloak server is running. +* Ensure that both RP and OpenID provider are using https instead of http. If the certificates or the CA is self-signed, ensure that they are added to the End-user certificate trust store. + +Procedure + +1. Install the mod_auth packages: +```console +# yum install mod_auth_openidc keycloak-httpd-client-install -y +``` +Note: OIDC support is added to the keycloak-httpd-client-install package with minimum requirement of version 1.x. + +2. Register Katello/Foreman as application in the Keycloak: +```console +# export KEYCLOAK_URL=https://keycloak.example.com +# export KEYCLOAK_REALM=ssl-realm +# export KEYCLOAK_USER=admin +# keycloak-httpd-client-install --app-name foreman-openidc --keycloak-server-url $KEYCLOAK_URL --keycloak-admin-username $KEYCLOAK_USER --keycloak-realm $KEYCLOAK_REALM --keycloak-admin-realm master --keycloak-auth-role root-admin -t openidc -l /users/extlogin -d +``` +Warning: This feature is not yet supported by foreman-installer. As a result, re-running the foreman-installer command can purge the changes in Apache files added by the keycloak-httpd-client-install. + +3. Log in to the Foreman admin page and click **Administer** → **Settings** → **Authentication**. + ![Foreman UI](Foreman_UI.png) + +4. Set **authorize_login_delegation_auth_source_user_autocreate** to **External** to enable auto-creation of users from external OpenID provider. + +5. Set the following OIDC parameters: + + **OIDC Algorithm**: Algorithm type with which JWT was encoded in the OpenID provider. For example, set this parameter to RS256. + + **OIDC Audience**: Name of the OIDC audience used for authentication. In case of Keycloak, it is Client ID. + + **OIDC Issuer**: The Issuer (iss) claim identifies the principal that issues the JWT. + + **OIDC JWKS URL**: Open JSON Web key Set URL to validate the signature. + + ![Foreman UI](Foreman_UI_Settings.png) + +#### End-user + +An end user can perform SSO by the following ways: +* User Interface +* Hammer-CLI + +To perform the mentioned ways, ensure that Foreman is configured. + +##### User Interface + +Procedure + +* Log in to the https://foreman.example.com/users/extlogin + + Foreman will automatically redirect to Keycloak Sign-in page. If credentials are correct, it redirects to the Foreman dashboard. + +##### Hammer-cli + +Hammer-cli supports the following methods to obtain ID token and perform authentication: + +* Authorization Code Grant Flow +* Password Grant Flow + +###### Authorization Code Grant Flow + +Authorization Code Flow is a two step process: + +* Authorization Code Flow returns an Authorization Code to the client. +* This Code can be exchanged for an access token directly. + +Procedure + +1. Get the token endpoint and authorization endpoint from the .well-known/openid-configuration URL of your OpenID provider. For example in case of Keycloak, get token and authorization endpoint from: https://<keycloak.example.com>/auth/realms/<realm-name>/.well-known/openid-configuration + +2. Log in to Foreman: +```console +hammer auth login oauth --two-factor --oidc-token-endpoint https://keycloak.example.com/token --oidc-authorization-endpoint https://keycloak.example.com/auth --oidc-client-id foreman-client --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob +``` + +###### Password Grant Flow + +The end user provides username and password for authentication and makes a POST request to the OpenID provider to exchange the password for an access token. + +Procedure + +1. Get token endpoint from the .well-known/openid-configuration URL of your OpenID provider. For example in case of Keycloak get token endpoint from: https://<keycloak.example.com>/auth/realms/<realm-name>/.well-known/openid-configuration + +2. Log in to Foreman: +```console +hammer auth login oauth --oidc-token-endpoint https://keycloak.example.com/token --oidc-client-id foreman-client --username myuser --password changeme +``` diff --git a/_includes/manuals/3.12/5.7_external_authentication.md b/_includes/manuals/3.12/5.7_external_authentication.md new file mode 100644 index 0000000000..e4aaafe251 --- /dev/null +++ b/_includes/manuals/3.12/5.7_external_authentication.md @@ -0,0 +1,2 @@ + +The following tutorial explains how to set up Foreman authentication against FreeIPA (or Identity Management) server. First part of the tutorial describes how to configure Foreman machine via Foreman installer options. The second one shows how to achieve the same result without using these options. diff --git a/_includes/manuals/3.12/5.8.1_database.md b/_includes/manuals/3.12/5.8.1_database.md new file mode 100644 index 0000000000..d7b051ceea --- /dev/null +++ b/_includes/manuals/3.12/5.8.1_database.md @@ -0,0 +1,2 @@ + +All Foreman instances in a cluster/group must point to the same database. This can be done during the initial installation (through flags or altering `foreman_installer_answers.yaml`) or by directly altering `/etc/foreman/database.yaml` and pointing the correct environment (usually production) to your Foreman DB, then restarting Foreman. diff --git a/_includes/manuals/3.12/5.8.2_encryption_rb.md b/_includes/manuals/3.12/5.8.2_encryption_rb.md new file mode 100644 index 0000000000..17a2400604 --- /dev/null +++ b/_includes/manuals/3.12/5.8.2_encryption_rb.md @@ -0,0 +1,2 @@ + +As described in [5.2.10](/manuals/{{page.version}}/index.html#5.2.10PasswordEncryption), passwords stored locally in Foreman's DB are encrypted. In order for multiple Foreman instances to encrypt and decrypt passwords correctly, they all need to have the same encryption key defined in `/etc/foreman/encryption_key.rb`. diff --git a/_includes/manuals/3.12/5.8.3_secret_token.md b/_includes/manuals/3.12/5.8.3_secret_token.md new file mode 100644 index 0000000000..fdb580fccd --- /dev/null +++ b/_includes/manuals/3.12/5.8.3_secret_token.md @@ -0,0 +1,9 @@ + +The last file required to make a Foreman cluster work is `$app_root/config/initializers/local_secret_token.rb`, which is used to sign cookies. This should be set the same across all Foreman servers in your cluster. Once you have set `local_secret_token.rb`, restart Foreman and clear Foreman's cache: +{% highlight bash %} +systemctl restart foreman +foreman-rake tmp:cache:clear +foreman-rake tmp:sessions:clear +{% endhighlight %} + +Note: Without this change, the user may need to log in multiple times or run in to "Invalid Authenticity Token"/CSRF issues. diff --git a/_includes/manuals/3.12/5.8.4_other_considerations.md b/_includes/manuals/3.12/5.8.4_other_considerations.md new file mode 100644 index 0000000000..fa75c7741f --- /dev/null +++ b/_includes/manuals/3.12/5.8.4_other_considerations.md @@ -0,0 +1,6 @@ + +There are other considerations when creating a cluster: + +1. You might want to share a common hostname, which can be set during installation or by modifying your Apache config files. +2. You might want a custom cert to reflect the cluster's cname, and you'll want to make sure your Foreman-related infrastructure is [configured to use SSL](manuals/{{page.version}}/index.html#5.4SecuringCommunicationswithSSL). +3. You can use a central Redis instance instead of each Foreman instance's local cache. diff --git a/_includes/manuals/3.12/5.8_multiple_foremen.md b/_includes/manuals/3.12/5.8_multiple_foremen.md new file mode 100644 index 0000000000..101be5ab62 --- /dev/null +++ b/_includes/manuals/3.12/5.8_multiple_foremen.md @@ -0,0 +1,4 @@ + +The following steps are suggested when configuring multiple Foreman instances to work together. They will ensure that data, passwords, and cookies are shared between multiple instances. + +`$app_root` is wherever you installed Foreman, usually `/usr/share/foreman`. diff --git a/_includes/manuals/3.12/5.9_http_proxy.md b/_includes/manuals/3.12/5.9_http_proxy.md new file mode 100644 index 0000000000..e48bbb2ebe --- /dev/null +++ b/_includes/manuals/3.12/5.9_http_proxy.md @@ -0,0 +1,33 @@ +There are two proxy settings in Foreman to allow HTTP(s) communication through +firewalls. + +*Global option* + +In Administer - Settings - General menu there are two options available for +setting outgoing HTTP(s) proxy for all communication (e.g. to Smart Proxies, +Compute Resources): + +* HTTP(S) proxy - hostname, port and optional credentials in the format of `http://[user:password@]HOST:PORT` +* HTTP(S) proxy except hosts - list of hostnames to exclude separated by commas + +Both settings can also be configured via `settings.yaml` file via +`:http_proxy:` and `:http_proxy_except_list:` options. + +*Infrastructure - HTTP Proxies page* + +It is possible to configure multiple HTTP(s) proxies for various Compute +Resources. Each individual Compute Resources can be associated with a different +proxy. To create proxy URL, visit Infrastructure - HTTP Proxies and then +associate the proxy with a Compute Resource. + +Currently HTTP Proxies are supported by the following Compute Resources: + +* EC2 +* Google Compute Engine + +*Notes* + +Both cases only affect outgoing HTTP(s) connection of the Foreman core +application (Ruby on Rails process). There are other plugins and components +running on a typical Foreman deployment (e.g. websocket proxy, Pulp, Candlepin) +and those services are not affected. Most of them can be configured separately. diff --git a/_includes/manuals/3.12/6_plugins.md b/_includes/manuals/3.12/6_plugins.md new file mode 100644 index 0000000000..fab6620c7d --- /dev/null +++ b/_includes/manuals/3.12/6_plugins.md @@ -0,0 +1 @@ +Please refer to the [plugins manual](/plugins/). diff --git a/_includes/manuals/3.12/7.1_novnc.md b/_includes/manuals/3.12/7.1_novnc.md new file mode 100644 index 0000000000..25ab95bc1f --- /dev/null +++ b/_includes/manuals/3.12/7.1_novnc.md @@ -0,0 +1,40 @@ +Foreman uses the excellent javascript VNC library [noVNC](https://novnc.com/info.html), which allows clientless VNC within a web browser. When a console is opened by the user's web browser, Foreman opens a connection to TCP Port 5910 (and up) on the hypervisor and redirects that itself. + +### Requirements + +* Recent web browser +* Open network connection from the workstation where the web browser runs on to your Foreman server and from your Foreman server to the hypervisor on TCP ports 5910 - 5930. + + +### Encrypted Web Sockets + +For VNC only, encrypted connections are the default on new installations. If you have an older installation of Foreman, you can configure encrypted websockets by adding these lines to `/etc/foreman/settings.yml`, and configuring the correct path to the same SSL certificates apache uses: + +```yaml +:websockets_encrypt: on +:websockets_ssl_key: /var/lib/puppet/ssl/private_keys/foreman.example.com +:websockets_ssl_cert: /var/lib/puppet/ssl/certs/foreman.example.com +``` + +### Known issues + +* SPICE connections are not encrypted. +* For encrypted connections, you will need to trust the Foreman CA. This is typically stored in /var/lib/puppet/ssl/certs/ca.pem, you may wish to copy this to something like /var/www/html/pub/ca.crt so that users may easily find it. +* Keyboard mappings are currently fixed to English only. +* When using Firefox, if you use Foreman via HTTPS, Firefox might block the connection. To fix it, go to `about:config` and enable `network.websocket.allowInsecureFromHTTPS`. +* When using Chrome, browse to `chrome://flags/` and enable allow-insecure-websocket-from-https-origin. Recent versions of Chrome (e.g. 44) have removed the flag. An alternative workaround is to launch Chrome with a command-line argument like this `$ google-chrome-stable --allow-running-insecure-content &` + +### Troubleshooting Steps + +* Check for a "websockify.py" process on your Foreman server when opening the console page in Foreman +* If websockify.py is missing, check /var/log/foreman/production.log for stderr output with logging increased to debug +* Look at the last argument of the process command line, it will have the hypervisor hostname and port - ensure you can resolve and ping this hostname +* Make sure you access Foreman web UI via FQDN as the certificate does not have shortened hostname. +* Try a telnet/netcat connection from the Foreman host to the hypervisor hostname/port +* The penultimate argument of websockify.py is the listening port number, check if your web client host can telnet to it +* If using Firefox, check the known issues above and set the config appropriately +* The error "WebSock error: [object Event]" can be caused by a self signed certificate, where the certificate`s algorithm is too weak, e.g. SHA1. +Debugging the issue with the Firefox JavaScript Console will show a warning similar to *"This site makes use of a SHA-1 Certificate; it's recommended you use certificates with signature algorithms that use hash functions stronger than SHA-1"*. See [Weak Signature Algorithms](https://developer.mozilla.org/docs/Security/Weak_Signature_Algorithm) on Mozilla website. + * To solve this issue, use stronger SSL certificates like SHA-2 algorithms instead. + * Check your current algorithm used for the SSL certificate with openssl and generate a new one if necessary: + * ```# openssl x509 -in /etc/ssl/certs/foreman.domain.tld.crt -text -noout |grep Algorithm Signature Algorithm: *sha1WithRSAEncryption*``` diff --git a/_includes/manuals/3.12/7.2_debugging.md b/_includes/manuals/3.12/7.2_debugging.md new file mode 100644 index 0000000000..5c288addab --- /dev/null +++ b/_includes/manuals/3.12/7.2_debugging.md @@ -0,0 +1,213 @@ + +### Foreman debugging + +Edit `/etc/foreman/settings.yaml` and either uncomment or add these lines: + +```yaml +:logging: + :level: debug +``` + +And reload Foreman: + + systemctl restart foreman + +#### Enabling more specific logs + +More types of log messages can be enabled from settings.yaml. The following loggers are enabled by default: + +* app - web requests and all general application logs +* audit - additional fact import statistics, numbers of facts added/updated/removed +* proxy - logs from reaching out to smart proxies +* notifications - logs from notification handlers +* backgroud - logs from background jobs like RSS or Dynflow +* dynflow - low level logs from dynflow engine +* templates - messages from template renderer +* blob - contents of rendered templates for archival purposes + +The following loggers needs to be explicitly enabled: + +* ldap - high level LDAP queries (e.g. find users in group) and LDAP operations performed (default: false) +* permissions - evaluation of user roles, filters and permissions when loading pages +* sql - SQL queries made through Rails ActiveRecord, only debug +* telemetry - logs for debugging telemetry messages + +Uncomment or add a :loggers block to enable or disable loggers: + +```yaml +:loggers: + :ldap: + :enabled: true +``` + +Plugins may add their own logs too, see /etc/foreman/plugins/ for their possible configuration. + +Also see [Configuration Options]({{ site.baseurl }}manuals/{{ page.version }}/index.html#3.5.2ConfigurationOptions) for more information. + +#### Structured logging + +Starting from Foreman 1.18, logging stack can be configured to log into system journal: + +```yaml +:logging: + :level: info + :type: journald +``` + +On Red Hat compatible systems, journald is running in transient mode by default and forwards all logs to syslog which means structured information is dropped after some time (memory buffer only holds few hours back). To see structured fields: + + journalctl -fo verbose + +Here is the list of most important structured fields which can help with debugging: + +<table class="table table-bordered table-condensed"> + <tr> + <th>Journald name</th> + <th>JSON name</th> + <th>Description</th> + </tr> + <tr> + <td>USER_LOGIN</td> + <td>["mdc"]["user_login"]</td> + <td>User login name</td> + </tr> + <tr> + <td>ORG_ID</td> + <td>["mdc"]["org_id"]</td> + <td>Organization database ID</td> + </tr> + <tr> + <td>LOC_ID</td> + <td>["mdc"]["loc_id"]</td> + <td>Location database ID</td> + </tr> + <tr> + <td>REMOTE_IP</td> + <td>["mdc"]["remote_ip"]</td> + <td>Remote IP address of a client</td> + </tr> + <tr> + <td>REQUEST</td> + <td>["mdc"]["request"]</td> + <td>Request ID generated by ActionDispatch</td> + </tr> + <tr> + <td>SESSION</td> + <td>["mdc"]["session"]</td> + <td>Random ID generated per session or request for session-less request</td> + </tr> + <tr> + <td>EXCEPTION_MESSAGE</td> + <td>["ndc"]["exception_message"]</td> + <td>Exception message when error is logged</td> + </tr> + <tr> + <td>EXCEPTION_CLASS</td> + <td>["ndc"]["exception_class"]</td> + <td>Exception Ruby class when error is logged</td> + </tr> + <tr> + <td>EXCEPTION_BACKTRACE</td> + <td>["ndc"]["exception_backtrace"]</td> + <td>Exception backtrace as a multiline string when error is logged</td> + </tr> + <tr> + <td>TEMPLATE_NAME</td> + <td>["ndc"]["template_name"]</td> + <td>Template name (blob logger)</td> + </tr> + <tr> + <td>TEMPLATE_DIGEST</td> + <td>["ndc"]["template_digest"]</td> + <td>Digest (SHA256) of rendered template contents (blob logger)</td> + </tr> + <tr> + <td>TEMPLATE_HOST_NAME</td> + <td>["ndc"]["template_host_name"]</td> + <td>Host name for a rendered template if present (blob logger)</td> + </tr> + <tr> + <td>TEMPLATE_HOST_ID</td> + <td>["ndc"]["template_host_id"]</td> + <td>Host database ID for a rendered template if present (blob logger)</td> + </tr> + <tr> + <td>AUDIT_ACTION</td> + <td>["ndc"]["audit_action"]</td> + <td>Action performed (e.g. create/update/delete)</td> + </tr> + <tr> + <td>AUDIT_TYPE</td> + <td>["ndc"]["audit"]</td> + <td>Database model class or type, subject of an audit record (e.g. Hostgroup or Subnet)</td> + </tr> + <tr> + <td>AUDIT_ID</td> + <td>["ndc"]["audit"]</td> + <td>Record database ID of the audit subject</td> + </tr> + <tr> + <td>AUDIT_ATTRIBUTE</td> + <td>["ndc"]["audit"]</td> + <td>Attribute name or column an action was performed on (e.g. name or description)</td> + </tr> +</table> + +To persist structured fields, enable persistent system journal by creating `/var/log/journal` directory. Alternatively, logging into JSON format can be used with syslog or file appenders for further integration: + +```yaml +:logging: + :level: info + :type: syslog + :json_items: + - logger + - timestamp + - level + - message + - mdc + - ndc + :facility: LOG_LOCAL6 +``` + +Structured fields from Foreman appear under "mdc" and "ndc" elements. The logging stack is able to provide additional context via `json_items` setting: + +* logger - the name of the logger that generated the log event. +* timestamp - the timestamp of the log event. +* level - the level of the log event. +* message - the application supplied message associated with the log event. +* file - the file name where the logging request was issued. +* line - the line number where the logging request was issued. +* method - the method name where the logging request was issued. +* hostname - the hostname +* pid - the process ID of the currently running program. +* millis - the number of milliseconds elapsed from the construction of the Layout until creation of the log event. +* thread_id - the object ID of the thread that generated the log event. +* thread - the name of the thread that generated the log event. Name can be specified using Thread.current[:name] notation. Output empty string if name not specified. This option helps to create more human readable output for multithread application logs. + +#### Syslog facility + +By default, syslog facility is set to LOCAL6 (or USER6). This can be changed via: + +```yaml +:logging: + :facility: LOG_LOCAL6 +``` + +To forward logs to separate directory via rsyslog, create file `/etc/rsyslog.d/foreman.conf`: + + local6.* /var/log/foreman/production.log + +### Smart proxy debugging + +Edit `/etc/foreman-proxy/settings.yml` and change or add :log_level: + +```yaml +# WARN, DEBUG, Error, Fatal, INFO, UNKNOWN +:log_level: DEBUG +``` + +And restart the smart proxy: + + service foreman-proxy restart + +Also see [Smart Proxy Settings]({{ site.baseurl }}manuals/{{ page.version }}/index.html#4.3.2SmartProxySettings) for more information. diff --git a/_includes/manuals/3.12/7.3_getting_help.md b/_includes/manuals/3.12/7.3_getting_help.md new file mode 100644 index 0000000000..e6c1d044bf --- /dev/null +++ b/_includes/manuals/3.12/7.3_getting_help.md @@ -0,0 +1,32 @@ +The two primary methods of getting support for Foreman are IRC and discussion forums. + +### IRC +We work on the [libera.chat](https://libera.chat/) servers. You can get general support in #theforeman, while development chat takes place in #theforeman-dev. + +### Discussion Forums + +An online discussion forum is available at https://community.theforeman.org/. Much like IRC, we have discussion areas for general users (support, Q/A, etc), as well as a discussion areas for developers, tutorials and release announcements. + +* [General Support](https://community.theforeman.org/c/support) +* [Development](https://community.theforeman.org/c/support) +* [Release Announcements](https://community.theforeman.org/c/release-announcements) + +### Gathering information +In order to troubleshoot and get relevant data use foreman-debug which collects information about your OS, Foreman and related components. +If you installed from packages, the command is available to root: + + # foreman-debug + +If you installed from git, you can find it in the Foreman directory: + + # script/foreman-debug + +If you run it without any options, it will collect data, filter out possible +passwords or tokens and create a tarball which can be safely handed over to +us. + +To upload the tarball to our public server via rsync use: + + # foreman-debug -u + +This is a write-only directory (readable only by Foreman core developers), please note that the rsync transmission is UNENCRYPTED. diff --git a/_includes/manuals/3.12/missing.html b/_includes/manuals/3.12/missing.html new file mode 100644 index 0000000000..04df1c8f3c --- /dev/null +++ b/_includes/manuals/3.12/missing.html @@ -0,0 +1 @@ +<span style='color: #cd5c5c;'>Missing content. Consider contributing, you kind soul!</span> \ No newline at end of file diff --git a/manuals/3.12/index.md b/manuals/3.12/index.md new file mode 100644 index 0000000000..f2407f2453 --- /dev/null +++ b/manuals/3.12/index.md @@ -0,0 +1,332 @@ +--- +layout: manual +title: Foreman 3.12 Manual +version: "3.12" +previous_version: "3.11" +--- + +# 1. {{ page.title }} +{% include manuals/{{ page.version }}/1.1_architecture.md %} +{% include manuals/{{ page.version }}/1.2_release_notes.md %} + +# 2. Quickstart +{% include manuals/{{ page.version }}/2_quickstart_guide.md %} +## 2.1 Installation +{% include manuals/{{ page.version }}/2.1_quickstart_installation.md %} +## 2.2 Puppet Management +{% include manuals/{{ page.version }}/2.2_quickstart_puppet.md %} + +# 3. Installing Foreman +{% include manuals/{{ page.version }}/3_installing_foreman.md %} +## 3.1 System Requirements +{% include manuals/{{ page.version }}/3.1_system_requirements.md %} +### 3.1.1 Supported Platforms +{% include manuals/{{ page.version }}/3.1.1_supported_platforms.md %} +### 3.1.2 Hardware Requirements +{% include manuals/{{ page.version }}/3.1.2_hardware_requirements.md %} +### 3.1.3 Puppet Compatibility +{% include manuals/{{ page.version }}/3.1.3_puppet_versions.md %} +### 3.1.4 Browser Compatibility +{% include manuals/{{ page.version }}/3.1.4_browser_compatibility.md %} +### 3.1.5 Firewall Configuration +{% include manuals/{{ page.version }}/3.1.5_firewall_configuration.md %} +## 3.2 Foreman Installer +{%include manuals/{{ page.version }}/3.2_foreman_installer.md %} +### 3.2.1 Installation +{%include manuals/{{ page.version }}/3.2.1_installation.md %} +### 3.2.2 Installer Options +{%include manuals/{{ page.version }}/3.2.2_installer_options.md %} +### 3.2.3 Installation Scenarios +{%include manuals/{{ page.version }}/3.2.3_installation_scenarios.md %} +## 3.3 Install From Packages +{%include manuals/{{ page.version }}/3.3_install_from_packages.md %} +### 3.3.1 RPM Packages +{%include manuals/{{ page.version }}/3.3.1_rpm_packages.md %} +### 3.3.2 Debian Packages +{%include manuals/{{ page.version }}/3.3.2_debian_packages.md %} +## 3.4 Install From Source +{%include manuals/{{ page.version }}/3.4_install_from_source.md %} +## 3.5 Configuration +{%include manuals/{{ page.version }}/3.5_configuration.md %} +### 3.5.1 Initial Setup +{%include manuals/{{ page.version }}/3.5.1_initial_setup.md %} +### 3.5.2 Configuration Options +{%include manuals/{{ page.version }}/3.5.2_configuration_options.md %} +### 3.5.3 Database Setup +{%include manuals/{{ page.version }}/3.5.3_database_setup.md %} +### 3.5.4 Puppet Reports +{%include manuals/{{ page.version }}/3.5.4_puppet_reports.md %} +### 3.5.5 Facts and the ENC +{%include manuals/{{ page.version }}/3.5.5_facts_and_the_enc.md %} +### 3.5.6 CLI +{%include manuals/{{ page.version }}/3.5.6_cli.md %} +## 3.6 Upgrade to {{ page.version }} +{%include manuals/{{ page.version }}/3.6_upgrade.md %} + +# 4. General Foreman +{%include manuals/{{ page.version }}/4_general_foreman.md %} +## 4.1 Web Interface + +### 4.1.1 LDAP Authentication +{%include manuals/{{ page.version }}/4.1.1_authentication.md %} +### 4.1.2 Roles and Permissions +{%include manuals/{{ page.version }}/4.1.2_roles_and_permissions.md %} +### 4.1.3 Trends +{%include manuals/{{ page.version }}/4.1.3_trends.md %} +### 4.1.4 Auditing +{%include manuals/{{ page.version }}/4.1.4_auditing.md %} +### 4.1.5 Searching +{%include manuals/{{ page.version }}/4.1.5_searching.md %} +### 4.1.6 User Management +{%include manuals/{{ page.version }}/4.1.6_user_management.md %} + +## 4.2 Managing Puppet +{%include manuals/{{ page.version }}/4.2_managing_puppet.md %} +### 4.2.1 Environments +{%include manuals/{{ page.version }}/4.2.1_puppet_envs.md %} +### 4.2.2 Classes +{%include manuals/{{ page.version }}/4.2.2_puppet_classes.md %} +### 4.2.3 Parameters +{%include manuals/{{ page.version }}/4.2.3_puppet_params.md %} +### 4.2.4 Parameterized Classes +{%include manuals/{{ page.version }}/4.2.4_param_classes.md %} +### 4.2.5 Smart Matchers +{%include manuals/{{ page.version }}/4.2.5_matchers.md %} + +## 4.3 Smart Proxies +{%include manuals/{{ page.version }}/4.3_smartproxy.md %} +### 4.3.1 Smart Proxy Installation +{%include manuals/{{ page.version }}/4.3.1_smartproxy_installation.md %} +### 4.3.2 Smart Proxy Settings +{%include manuals/{{ page.version }}/4.3.2_smartproxy_settings.md %} + +### 4.3.3 BMC +{%include manuals/{{ page.version }}/4.3.3_smartproxy_bmc.md %} +#### 4.3.3.1 SSH BMC +{%include manuals/{{ page.version }}/4.3.3.1_smartproxy_bmc_ssh.md %} + +### 4.3.4 DHCP + +#### 4.3.4.1 dhcp.yml +{%include manuals/{{ page.version }}/4.3.4_smartproxy_dhcp.md %} +#### 4.3.4.2 ISC DHCP +{%include manuals/{{ page.version }}/4.3.4.2_isc_dhcp.md %} +#### 4.3.4.3 MS DHCP +{%include manuals/{{ page.version }}/4.3.4.3_ms_dhcp.md %} + +### 4.3.5 DNS + +#### 4.3.5.1 dns.yml +{%include manuals/{{ page.version }}/4.3.5_smartproxy_dns.md %} +#### 4.3.5.2 BIND +{%include manuals/{{ page.version }}/4.3.5.2_bind.md %} +#### 4.3.5.3 GSS-TSIG DNS +{%include manuals/{{ page.version }}/4.3.5.3_gsstsig.md %} + +### 4.3.6 Puppet +{%include manuals/{{ page.version }}/4.3.6_smartproxy_puppet.md %} +### 4.3.7 Puppet CA +{%include manuals/{{ page.version }}/4.3.7_smartproxy_puppetca.md %} + +### 4.3.8 Realm + +#### 4.3.8.1 realm.yml +{%include manuals/{{ page.version }}/4.3.8_smartproxy_realm.md %} +#### 4.3.8.2 FreeIPA Realm +{%include manuals/{{ page.version }}/4.3.8.2_freeipa_realm.md %} + +### 4.3.9 TFTP +{%include manuals/{{ page.version }}/4.3.9_smartproxy_tftp.md %} +### 4.3.10 SSL +{%include manuals/{{ page.version }}/4.3.10_smartproxy_ssl.md %} +### 4.3.11 Libvirt +{%include manuals/{{ page.version }}/4.3.11_smartproxy_libvirt.md %} +### 4.3.12 Templates +{%include manuals/{{ page.version }}/4.3.12_smartproxy_templates.md %} +### 4.3.13 Logs +{%include manuals/{{ page.version }}/4.3.13_smartproxy_logs.md %} + +## 4.4 Provisioning +{%include manuals/{{ page.version }}/4.4_provisioning.md %} +### 4.4.1 Operating Systems +{%include manuals/{{ page.version }}/4.4.1_prov_os.md %} +### 4.4.2 Installation Media +{%include manuals/{{ page.version }}/4.4.2_prov_media.md %} +### 4.4.3 Provisioning Templates +{%include manuals/{{ page.version }}/4.4.3_prov_templates.md %} +### 4.4.4 Partition Tables +{%include manuals/{{ page.version }}/4.4.4_prov_ptables.md %} +### 4.4.5 Architectures +{%include manuals/{{ page.version }}/4.4.4_prov_archs.md %} +### 4.4.6 Workflow +{%include manuals/{{ page.version }}/4.4.6_prov_workflow.md %} +### 4.4.7 Networking +{%include manuals/{{ page.version }}/4.4.7_prov_networking.md %} +### 4.4.8 OS Specific Notes +{%include manuals/{{ page.version }}/4.4.8_prov_os_notes.md %} +### 4.4.8.1 FreeBSD +{%include manuals/{{ page.version }}/4.4.8.1_prov_freebsd.md %} +### 4.4.8.2 SLES +{%include manuals/{{ page.version }}/4.4.8.2_prov_sles.md %} +### 4.4.8.3 Windows +{%include manuals/{{ page.version }}/4.4.8.3_prov_windows.md %} + +## 4.5 Command Line Interface +{%include manuals/{{ page.version }}/4.5_cli.md %} +### 4.5.1 Usage Examples +{%include manuals/{{ page.version }}/4.5.1_cli_examples.md %} +### 4.5.2 Success Story +{%include manuals/{{ page.version }}/4.5.2_cli_success.md %} + +## 4.6 Email Management +{%include manuals/{{ page.version }}/4.6_email.md %} +### 4.6.1 Email Preferences +{%include manuals/{{ page.version }}/4.6.1_email_preferences.md %} +### 4.6.2 Account Notifications +{%include manuals/{{ page.version }}/4.6.2_email_account.md %} +### 4.6.3 Host Notifications +{%include manuals/{{ page.version }}/4.6.3_email_host.md %} +### 4.6.4 Scheduled Emails +{%include manuals/{{ page.version }}/4.6.4_email_scheduled.md %} + +## 4.7 Managing Ansible +{%include manuals/{{ page.version }}/4.7_managing_ansible.md %} + +## 4.8 Managing Chef +{%include manuals/{{ page.version }}/4.8_managing_chef.md %} + +## 4.9 Managing Salt +{%include manuals/{{ page.version }}/4.9_managing_salt.md %} + +## 4.10 Monitoring +{%include manuals/{{ page.version }}/4.10_monitoring.md %} +### 4.10.1 Global status +{%include manuals/{{ page.version }}/4.10.1_global_status.md %} +### 4.10.2 Sub-statuses +{%include manuals/{{ page.version }}/4.10.2_substatuses.md %} +### 4.10.3 Searching by statuses +{%include manuals/{{ page.version }}/4.10.3_searching_by_statuses.md %} + +## 4.11 Reports +{%include manuals/{{ page.version }}/4.11_reports.md %} +### 4.11.1 Report Templates +{%include manuals/{{ page.version }}/4.11.1_report_templates.md %} +### 4.11.2 Macros +{%include manuals/{{ page.version }}/4.11.2_macros.md %} + +# 5. Advanced Foreman + +## 5.1 API +{%include manuals/{{ page.version }}/5.1_api.md %} +### 5.1.1 CRUD Request Examples +{%include manuals/{{ page.version }}/5.1.1_request_examples.md %} +### 5.1.2 JSON Response Format for Collections +{%include manuals/{{ page.version }}/5.1.2_api_json_collections.md %} +### 5.1.3 JSON Response Format for Single Objects +{%include manuals/{{ page.version }}/5.1.3_api_json_single_objects.md %} +### 5.1.4 Customize JSON Responses +{%include manuals/{{ page.version }}/5.1.4_api_customize.md %} +### 5.1.5 Nested API routes +{%include manuals/{{ page.version }}/5.1.5_nested_api_routes.md %} +### 5.1.6 API Versioning +{%include manuals/{{ page.version }}/5.1.6_versioning.md %} +### 5.1.7 Handling Associations +{%include manuals/{{ page.version }}/5.1.7_associations.md %} +### 5.1.8 Authentication +{%include manuals/{{ page.version }}/5.1.8_authentication.md %} +### 5.1.9 Using OAuth +{%include manuals/{{ page.version }}/5.1.9_oauth.md %} +### 5.1.10 Using Apipie-Bindings +{%include manuals/{{ page.version }}/5.1.10_apipie-bindings.md %} +### 5.1.11 Using Graphql +{%include manuals/{{ page.version }}/5.1.11_graphql.md %} +### 5.1.12 Dynflow scaling +{%include manuals/{{ page.version }}/5.1.12_dynflow_scaling.md %} + +## 5.2 Compute Resources +{%include manuals/{{ page.version }}/5.2_compute_resources.md %} +### 5.2.1 Using Compute Resources +{%include manuals/{{ page.version }}/5.2.1_cr_using.md %} +### 5.2.2 Using Compute Profiles +{%include manuals/{{ page.version }}/5.2.2_cr_profiles.md %} +### 5.2.3 EC2 Notes +{%include manuals/{{ page.version }}/5.2.3_cr_ec2.md %} +### 5.2.4 Google Compute Engine Notes +{%include manuals/{{ page.version }}/5.2.4_cr_gce.md %} +### 5.2.5 Libvirt Notes +{%include manuals/{{ page.version }}/5.2.5_cr_libvirt.md %} +### 5.2.6 OpenStack Notes +{%include manuals/{{ page.version }}/5.2.6_cr_openstack.md %} +### 5.2.7 oVirt / RHEV Notes +{%include manuals/{{ page.version }}/5.2.7_cr_ovirt.md %} +### 5.2.8 VMware Notes +{%include manuals/{{ page.version }}/5.2.8_cr_vmware.md %} +### 5.2.9 Password Encryption +{%include manuals/{{ page.version }}/5.2.9_cr_encryption_key.md %} + +## 5.3 Install Locations +{%include manuals/{{ page.version }}/missing.html %} +- + +## 5.4 Securing Communications with SSL +{%include manuals/{{ page.version }}/5.4_communications.md %} +### 5.4.1 Securing Puppet Server Requests +{%include manuals/{{ page.version }}/5.4.1_comms_puppetserver.md %} +### 5.4.2 Securing Smart Proxy Requests +{%include manuals/{{ page.version }}/5.4.2_comms_proxy.md %} +## 5.5 Backup, Recovery and Migration +{%include manuals/{{ page.version }}/5.5_backup_and_recovery.md %} +### 5.5.1 Backup +{%include manuals/{{ page.version }}/5.5.1_backup.md %} +### 5.5.2 Recovery +{%include manuals/{{ page.version }}/5.5.2_recovery.md %} + +## 5.6 Rails Console +{%include manuals/{{ page.version }}/5.6_rails_console.md %} + +<a id="5.7SPNEGOauthentication"></a> + +## 5.7 External Authentication +{%include manuals/{{ page.version }}/5.7_external_authentication.md %} +### 5.7.1 Configuration via Foreman installer +{%include manuals/{{ page.version }}/5.7.1_quick_configuration.md %} +### 5.7.2 HBAC configuration +{%include manuals/{{ page.version }}/5.7.2_HBAC_rules.md %} +### 5.7.3 Kerberos Single Sign-On +{%include manuals/{{ page.version }}/5.7.3_kerberos.md %} +### 5.7.4 PAM Authentication +{%include manuals/{{ page.version }}/5.7.4_pam_authentication.md %} +### 5.7.5 Populate users and attributes +{%include manuals/{{ page.version }}/5.7.5_populate_users_attributes_groups.md %} +### 5.7.6 Namespace separation +{%include manuals/{{ page.version }}/5.7.6_namespace_separation.md %} +### 5.7.7 Single Sign-on for Foreman using OpenID Connect protocol +{%include manuals/{{ page.version }}/5.7.7_openid_sso.md %} + +## 5.8 Multiple Foreman instances +{%include manuals/{{ page.version }}/5.8_multiple_foremen.md %} +### 5.8.1 Sharing the database +{%include manuals/{{ page.version }}/5.8.1_database.md %} +### 5.8.2 Encrypting passwords +{%include manuals/{{ page.version }}/5.8.2_encryption_rb.md %} +### 5.8.3 Signing cookies +{%include manuals/{{ page.version }}/5.8.3_secret_token.md %} +### 5.8.4 Other considerations +{%include manuals/{{ page.version }}/5.8.4_other_considerations.md %} + +## 5.9 HTTP(S) Proxy +{%include manuals/{{ page.version }}/5.9_http_proxy.md %} + +# 6. Plugins +{%include manuals/{{ page.version }}/6_plugins.md %} + +# 7. Troubleshooting + +## 7.1 NoVNC +{%include manuals/{{ page.version }}/7.1_novnc.md %} + +## 7.2 Debugging +{%include manuals/{{ page.version }}/7.2_debugging.md %} + +## 7.3 Getting Help +{%include manuals/{{ page.version }}/7.3_getting_help.md %} diff --git a/manuals/3.12/quickstart_guide.md b/manuals/3.12/quickstart_guide.md new file mode 100644 index 0000000000..a5fe35078e --- /dev/null +++ b/manuals/3.12/quickstart_guide.md @@ -0,0 +1,28 @@ +--- +layout: quickstart +title: Foreman Quickstart Guide +version: "3.12" +--- + +# Quickstart Guide + +{% include manuals/{{ page.version }}/2_quickstart_guide.md %} + +## Installation + +{% include manuals/{{ page.version }}/2.1_quickstart_installation.md %} + +## More quickstart resources... + +Continue reading the quickstart guide in the manual: + +* [Quickstart: Puppet management](/manuals/{{page.version}}/index.html#2.2PuppetManagement) + +Or view the quickstart screencasts: + +* [Quickstart screencasts](/media.html#screencasts) + +## Additional reading... + +* [Manual installation and further reading](/manuals/{{page.version}}/index.html) +* [More installation options and scenarios](/manuals/{{page.version}}/index.html#3.2.2InstallerOptions) diff --git a/manuals/nightly/index.md b/manuals/nightly/index.md index 8006e4e332..60d7ae4141 100644 --- a/manuals/nightly/index.md +++ b/manuals/nightly/index.md @@ -2,7 +2,7 @@ layout: manual title: Foreman Nightly Manual version: "nightly" -previous_version: "3.11" +previous_version: "3.12" --- # 1. {{ page.title }} From afe2833878d588c825c6d946c858667b4eb56adf Mon Sep 17 00:00:00 2001 From: Cole Higgins <chiggins@redhat.com> Date: Thu, 22 Aug 2024 12:15:44 -0400 Subject: [PATCH 2/4] Update release notes --- _includes/manuals/3.12/1.2_release_notes.md | 122 +++++++++++++++++++- 1 file changed, 121 insertions(+), 1 deletion(-) diff --git a/_includes/manuals/3.12/1.2_release_notes.md b/_includes/manuals/3.12/1.2_release_notes.md index c042901c21..94e3f07a79 100644 --- a/_includes/manuals/3.12/1.2_release_notes.md +++ b/_includes/manuals/3.12/1.2_release_notes.md @@ -8,7 +8,127 @@ This section will be updated prior to the next release. ### Deprecations -### Release Notes +### Release notes for 3.12.0 + +#### Foreman +* Add product host count to 'Subscription - General Report' ([#37756](https://projects.theforeman.org/issues/37756)) +* Fix audit message about removing records ([#37734](https://projects.theforeman.org/issues/37734)) +* Change All Hosts kebab menu to match mockup [Foreman] ([#37675](https://projects.theforeman.org/issues/37675)) +* Invalid MAC address error message appears twice while editing interface ([#37651](https://projects.theforeman.org/issues/37651)) +* Curl command cannot be rendered during host registration due to Loc/Org mismatch ([#37640](https://projects.theforeman.org/issues/37640)) +* FFI 1.17.0+ requires Rubygems 3.3.22+ for installation, breaking Ruby 2.7 source installs ([#37607](https://projects.theforeman.org/issues/37607)) +* Monitor -&gt; Host statusses shows "Pending Installation" instead of Installed ([#37589](https://projects.theforeman.org/issues/37589)) +* [RFE] Provisioning Templates or RHEL 9 should have option timesource ([#37581](https://projects.theforeman.org/issues/37581)) +* Improved "EFI local chainloading" on SecureBoot enabled hosts not working for all distribution ([#37562](https://projects.theforeman.org/issues/37562)) +* As a web UI user, I can select multiple hosts and perform a bulk change of the hostgroup ([#37551](https://projects.theforeman.org/issues/37551)) +* per_page=all doesn't work for parameters of subnets, domains, organizations.... ([#37550](https://projects.theforeman.org/issues/37550)) +* HostsIndex page should gracefully handle when 'Any organization' is selected ([#37548](https://projects.theforeman.org/issues/37548)) +* Append domain name setting ([#37532](https://projects.theforeman.org/issues/37532)) +* cleanup media dup ([#37527](https://projects.theforeman.org/issues/37527)) +* Plugins are finalized before seeds are executed ([#37503](https://projects.theforeman.org/issues/37503)) +* Unify sending built status in host_init_config ([#37495](https://projects.theforeman.org/issues/37495)) +* Fix Style/CaseLikeIf cop ([#37458](https://projects.theforeman.org/issues/37458)) +* Cloudinit default generates invalid yaml output ([#37433](https://projects.theforeman.org/issues/37433)) +* Fix Style/ExplicitBlockArgument cop ([#37428](https://projects.theforeman.org/issues/37428)) +* Rubocop minitest rules fix ([#37426](https://projects.theforeman.org/issues/37426)) +* Fix Style/RedundantRegexpEscape cop ([#37424](https://projects.theforeman.org/issues/37424)) +* Open Fix Style/HashEachMethods cop ([#37423](https://projects.theforeman.org/issues/37423)) +* Fix Style/AccessorGrouping cop ([#37420](https://projects.theforeman.org/issues/37420)) +* As a web UI user, I can select multiple hosts and perform build actions ([#37395](https://projects.theforeman.org/issues/37395)) +* Improve "EFI local chainloading" on SecureBoot enabled hosts ([#37345](https://projects.theforeman.org/issues/37345)) +* Help page should not link libera chat anymore after the migration to matrix ([#37086](https://projects.theforeman.org/issues/37086)) +* Possibility to use selenium remote driver ([#36978](https://projects.theforeman.org/issues/36978)) +* Upload facts after host provisioning ([#36886](https://projects.theforeman.org/issues/36886)) +* Fix parsing of Ubuntu version in fact parsers ([#36547](https://projects.theforeman.org/issues/36547)) + +#### Foreman - Compute resources - VMware +* Feature Request: Support of NVMe controllers for VMware ([#34839](https://projects.theforeman.org/issues/34839)) + +#### Foreman - Compute resources - libvirt +* Drop CPU model for libvirt VM creation ([#36999](https://projects.theforeman.org/issues/36999)) + +#### Foreman - Host registration +* Host remains in build mode during registration when setup_insights is set to true ([#37720](https://projects.theforeman.org/issues/37720)) +* Find methods for taxonomies ([#37702](https://projects.theforeman.org/issues/37702)) + +#### Foreman - JavaScript stack +* Drop coffee-rails dependency ([#37583](https://projects.theforeman.org/issues/37583)) +* Content Columns can disappear from the Manage Columns widget on the redesigned All Hosts Page ([#37553](https://projects.theforeman.org/issues/37553)) +* Change I18n loading from import to require ([#37300](https://projects.theforeman.org/issues/37300)) + +#### Foreman - Organizations and Locations +* Smart Proxy forces association to all Locations unless Puppet is enabled on the proxy ([#29450](https://projects.theforeman.org/issues/29450)) + +#### Foreman - Proxy gateway +* Test Connection' button in 'New HTTP Proxy' returns success with invalid URL ([#36919](https://projects.theforeman.org/issues/36919)) + +#### Foreman - Settings +* The description of a setting Instance color contains additional dot ([#37597](https://projects.theforeman.org/issues/37597)) + +#### Foreman - Templates +* Create a way to refresh CA certificates on hosts that are managed by Katello ([#37601](https://projects.theforeman.org/issues/37601)) +* RHEL registration template ignores host_parm subscription_manager_org ([#37496](https://projects.theforeman.org/issues/37496)) +* Templates - cloned_from reference ([#37059](https://projects.theforeman.org/issues/37059)) +* Template render error when no PXELoader is selected ([#36626](https://projects.theforeman.org/issues/36626)) + +#### Foreman - Tests +* nic_managed factory can create an IP outside of its subnet ([#37711](https://projects.theforeman.org/issues/37711)) +* Report renderer tests fail depending on the libyaml version ([#37613](https://projects.theforeman.org/issues/37613)) +* with_temporary_settings test helper doesn't clean up properly ([#37558](https://projects.theforeman.org/issues/37558)) + +#### Foreman - Unattended installations +* Use SHA512 for root password hashing when no OS is set ([#37614](https://projects.theforeman.org/issues/37614)) +* HostCommon.crypt_passwords reencrypts Base64 based passwords for Grub, leading to errors ([#37610](https://projects.theforeman.org/issues/37610)) +* Extend Windows support in templates ([#36495](https://projects.theforeman.org/issues/36495)) + +#### Foreman - Web Interface +* Add button linking to new All Hosts UI ([#37690](https://projects.theforeman.org/issues/37690)) +* Show complete hostgroup name in host overview and table ([#37648](https://projects.theforeman.org/issues/37648)) +* Tab title missing in tableindexpage ([#37645](https://projects.theforeman.org/issues/37645)) +* Pagination doesnt always update between react pages ([#37644](https://projects.theforeman.org/issues/37644)) +* Template render error when host has .ics domain name ([#37623](https://projects.theforeman.org/issues/37623)) +* Host details - Fix append domain setting ([#37584](https://projects.theforeman.org/issues/37584)) +* use textarea in host comment edit ([#37582](https://projects.theforeman.org/issues/37582)) +* remove space between table buttons ([#37578](https://projects.theforeman.org/issues/37578)) +* Foreman Table columns sort is inconsistent ([#37575](https://projects.theforeman.org/issues/37575)) +* Cancel build shows notification with host id instead of hostname on the new UI of Red Hat Satellite ([#37556](https://projects.theforeman.org/issues/37556)) +* New All Hosts page ignores pagination url params on first load ([#37485](https://projects.theforeman.org/issues/37485)) +* Add Power Status column to new All Hosts page ([#37478](https://projects.theforeman.org/issues/37478)) +* Extend TableIndexPage and TableHooks with new capabilities for All Hosts page ([#37398](https://projects.theforeman.org/issues/37398)) + +#### Installer +* After an OS version upgrade, the GUI still shows the old/wrong Operating System version ([#37726](https://projects.theforeman.org/issues/37726)) +* Disable port 8443 by default ([#37701](https://projects.theforeman.org/issues/37701)) +* Installler doesn't handle Puppetserver 8 upgrade ([#37686](https://projects.theforeman.org/issues/37686)) +* Correct docroot for Content Proxies's Apache vhost ([#37620](https://projects.theforeman.org/issues/37620)) +* Possibility to set puppet version in gitlab CI ([#37568](https://projects.theforeman.org/issues/37568)) + +#### Installer - Foreman modules +* Pasing --foreman-proxy-content-enable-docker false can leave smart_proxy_container_gateway in an inconsistent state ([#37707](https://projects.theforeman.org/issues/37707)) +* DNS forwarders aren't validated ([#37604](https://projects.theforeman.org/issues/37604)) + +#### Installer - foreman-installer script +* Add check for ipv6.disable=1 in /proc/cmdline because it's known to break installations ([#37693](https://projects.theforeman.org/issues/37693)) + +#### Packaging - RPMs +* Make foreman-installer-katello pull in foreman-maintain ([#37663](https://projects.theforeman.org/issues/37663)) + +#### SELinux - Plugins +* Boot disk based Provisioning fails to generate ISO image for instance clietn.example.com: ERF42-8093 [Foreman::Exception]: ISO build failed ([#37497](https://projects.theforeman.org/issues/37497)) + +#### Smart Proxy +* Maximum sessions limit reached on iDRAC using Redfish as BMC provider ([#37486](https://projects.theforeman.org/issues/37486)) + +#### Smart Proxy - DHCP +* invalid value for Integer(): “#Resolv::DNS::Resource::IN::A:0x00007fnnnnnnnnn” ([#37621](https://projects.theforeman.org/issues/37621)) + +#### Smart Proxy - Packaging +* Pin FFI to &lt; 1.17 on Ruby 2.x ([#37624](https://projects.theforeman.org/issues/37624)) + +#### Smart Proxy - Registration +* Host registration with repositories fails because smart-proxy cannot convert arrays to string ([#37631](https://projects.theforeman.org/issues/37631)) + +*A full list of changes in 3.12.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]=1836)* ### Contributors From e15bb6ef71cd38c7dd6faaad266e48ada637d7ff Mon Sep 17 00:00:00 2001 From: Cole Higgins <chiggins@redhat.com> Date: Thu, 22 Aug 2024 12:57:57 -0400 Subject: [PATCH 3/4] Add contributors to release notes --- _includes/manuals/3.12/1.2_release_notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/manuals/3.12/1.2_release_notes.md b/_includes/manuals/3.12/1.2_release_notes.md index 94e3f07a79..bca4a58d55 100644 --- a/_includes/manuals/3.12/1.2_release_notes.md +++ b/_includes/manuals/3.12/1.2_release_notes.md @@ -134,6 +134,6 @@ This section will be updated prior to the next release. 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 --> +Adam Lazik,Adam Růžička,Aneta Šteflová Petrová,Archana Kumari,Beat Gaetzi,Bernhard Suttner,Chris Roberts,Cole Higgins,Dirk Götz,Eric Helms,Evgeni Golov,Ewoud Kohl van Wijngaarden,Girija Soni,Griffin-Sullivan,Jan Löser,Jeremy Lenz,Joniel Pasqualetto,Laurent Bigonville,Leos Stejskal,Marek Hulán,Maria Agaphontzev,Markus Reisner,Martin Alfke,Maximilian Kolb,Nadja Heitmann,Nofar Alfassi,Oleh Fedorenko,Partha Aji,Patrick Creech,Quinn James,RhinoX,Richard Stempfl,Romuald Conty,Samir Jha,Sayan Das,Shimon Shtein,William Bradford Clark,akumari,dosas,girijaasoni,kmalyjur,omahs As well as all users who helped test releases, report bugs and provide feedback on the project. From 71c0a4c115064d79835d723f952d48dfeaa05fd9 Mon Sep 17 00:00:00 2001 From: Cole Higgins <chiggins@redhat.com> Date: Thu, 22 Aug 2024 16:49:03 -0400 Subject: [PATCH 4/4] update release notes and files from nightly --- _includes/manuals/3.12/1.2_release_notes.md | 102 ++++++++++-------- .../manuals/3.12/4.3.7_smartproxy_puppetca.md | 37 ------- 2 files changed, 58 insertions(+), 81 deletions(-) diff --git a/_includes/manuals/3.12/1.2_release_notes.md b/_includes/manuals/3.12/1.2_release_notes.md index bca4a58d55..d9f981536b 100644 --- a/_includes/manuals/3.12/1.2_release_notes.md +++ b/_includes/manuals/3.12/1.2_release_notes.md @@ -11,35 +11,10 @@ This section will be updated prior to the next release. ### Release notes for 3.12.0 #### Foreman -* Add product host count to 'Subscription - General Report' ([#37756](https://projects.theforeman.org/issues/37756)) * Fix audit message about removing records ([#37734](https://projects.theforeman.org/issues/37734)) -* Change All Hosts kebab menu to match mockup [Foreman] ([#37675](https://projects.theforeman.org/issues/37675)) -* Invalid MAC address error message appears twice while editing interface ([#37651](https://projects.theforeman.org/issues/37651)) -* Curl command cannot be rendered during host registration due to Loc/Org mismatch ([#37640](https://projects.theforeman.org/issues/37640)) -* FFI 1.17.0+ requires Rubygems 3.3.22+ for installation, breaking Ruby 2.7 source installs ([#37607](https://projects.theforeman.org/issues/37607)) -* Monitor -&gt; Host statusses shows "Pending Installation" instead of Installed ([#37589](https://projects.theforeman.org/issues/37589)) -* [RFE] Provisioning Templates or RHEL 9 should have option timesource ([#37581](https://projects.theforeman.org/issues/37581)) -* Improved "EFI local chainloading" on SecureBoot enabled hosts not working for all distribution ([#37562](https://projects.theforeman.org/issues/37562)) -* As a web UI user, I can select multiple hosts and perform a bulk change of the hostgroup ([#37551](https://projects.theforeman.org/issues/37551)) + +#### Foreman - API * per_page=all doesn't work for parameters of subnets, domains, organizations.... ([#37550](https://projects.theforeman.org/issues/37550)) -* HostsIndex page should gracefully handle when 'Any organization' is selected ([#37548](https://projects.theforeman.org/issues/37548)) -* Append domain name setting ([#37532](https://projects.theforeman.org/issues/37532)) -* cleanup media dup ([#37527](https://projects.theforeman.org/issues/37527)) -* Plugins are finalized before seeds are executed ([#37503](https://projects.theforeman.org/issues/37503)) -* Unify sending built status in host_init_config ([#37495](https://projects.theforeman.org/issues/37495)) -* Fix Style/CaseLikeIf cop ([#37458](https://projects.theforeman.org/issues/37458)) -* Cloudinit default generates invalid yaml output ([#37433](https://projects.theforeman.org/issues/37433)) -* Fix Style/ExplicitBlockArgument cop ([#37428](https://projects.theforeman.org/issues/37428)) -* Rubocop minitest rules fix ([#37426](https://projects.theforeman.org/issues/37426)) -* Fix Style/RedundantRegexpEscape cop ([#37424](https://projects.theforeman.org/issues/37424)) -* Open Fix Style/HashEachMethods cop ([#37423](https://projects.theforeman.org/issues/37423)) -* Fix Style/AccessorGrouping cop ([#37420](https://projects.theforeman.org/issues/37420)) -* As a web UI user, I can select multiple hosts and perform build actions ([#37395](https://projects.theforeman.org/issues/37395)) -* Improve "EFI local chainloading" on SecureBoot enabled hosts ([#37345](https://projects.theforeman.org/issues/37345)) -* Help page should not link libera chat anymore after the migration to matrix ([#37086](https://projects.theforeman.org/issues/37086)) -* Possibility to use selenium remote driver ([#36978](https://projects.theforeman.org/issues/36978)) -* Upload facts after host provisioning ([#36886](https://projects.theforeman.org/issues/36886)) -* Fix parsing of Ubuntu version in fact parsers ([#36547](https://projects.theforeman.org/issues/36547)) #### Foreman - Compute resources - VMware * Feature Request: Support of NVMe controllers for VMware ([#34839](https://projects.theforeman.org/issues/34839)) @@ -47,76 +22,115 @@ This section will be updated prior to the next release. #### Foreman - Compute resources - libvirt * Drop CPU model for libvirt VM creation ([#36999](https://projects.theforeman.org/issues/36999)) +#### Foreman - Development tools +* Fix Style/CaseLikeIf cop ([#37458](https://projects.theforeman.org/issues/37458)) +* Fix Style/ExplicitBlockArgument cop ([#37428](https://projects.theforeman.org/issues/37428)) +* Rubocop minitest rules fix ([#37426](https://projects.theforeman.org/issues/37426)) +* Fix Style/RedundantRegexpEscape cop ([#37424](https://projects.theforeman.org/issues/37424)) +* Fix Style/HashEachMethods cop violations ([#37423](https://projects.theforeman.org/issues/37423)) +* Fix Style/AccessorGrouping cop violations ([#37420](https://projects.theforeman.org/issues/37420)) + +#### Foreman - Facts +* Fix parsing of Ubuntu version in fact parsers ([#36547](https://projects.theforeman.org/issues/36547)) + #### Foreman - Host registration * Host remains in build mode during registration when setup_insights is set to true ([#37720](https://projects.theforeman.org/issues/37720)) -* Find methods for taxonomies ([#37702](https://projects.theforeman.org/issues/37702)) +* Provide methods to find taxonomies in host registration for use in plugins ([#37702](https://projects.theforeman.org/issues/37702)) +* Curl command cannot be rendered during host registration due to Loc/Org mismatch ([#37640](https://projects.theforeman.org/issues/37640)) +* Unify sending built status in host_init_config ([#37495](https://projects.theforeman.org/issues/37495)) + +#### Foreman - Inventory +* Add button linking to new All Hosts UI ([#37690](https://projects.theforeman.org/issues/37690)) +* Change All Hosts kebab menu to match mockup ([#37675](https://projects.theforeman.org/issues/37675)) +* Invalid MAC address error message appears twice while editing interface ([#37651](https://projects.theforeman.org/issues/37651)) +* Append domain setting results in broken host details page with long hostnames or hosts without domain ([#37584](https://projects.theforeman.org/issues/37584)) +* use textarea in host comment edit ([#37582](https://projects.theforeman.org/issues/37582)) +* Content Columns can disappear from the Manage Columns widget on the redesigned All Hosts Page ([#37553](https://projects.theforeman.org/issues/37553)) +* As a web UI user, I can select multiple hosts and perform a bulk change of the hostgroup ([#37551](https://projects.theforeman.org/issues/37551)) +* HostsIndex page should gracefully handle when 'Any organization' is selected ([#37548](https://projects.theforeman.org/issues/37548)) +* New All Hosts page ignores pagination url params on first load ([#37485](https://projects.theforeman.org/issues/37485)) +* Add Power Status column to new All Hosts page ([#37478](https://projects.theforeman.org/issues/37478)) +* Extend TableIndexPage and TableHooks with new capabilities for All Hosts page ([#37398](https://projects.theforeman.org/issues/37398)) +* As a web UI user, I can select multiple hosts and perform build actions ([#37395](https://projects.theforeman.org/issues/37395)) #### Foreman - JavaScript stack * Drop coffee-rails dependency ([#37583](https://projects.theforeman.org/issues/37583)) -* Content Columns can disappear from the Manage Columns widget on the redesigned All Hosts Page ([#37553](https://projects.theforeman.org/issues/37553)) * Change I18n loading from import to require ([#37300](https://projects.theforeman.org/issues/37300)) #### Foreman - Organizations and Locations +* Property media is assigned twice in the same method ([#37527](https://projects.theforeman.org/issues/37527)) * Smart Proxy forces association to all Locations unless Puppet is enabled on the proxy ([#29450](https://projects.theforeman.org/issues/29450)) +#### Foreman - Packaging +* FFI 1.17.0+ requires Rubygems 3.3.22+ for installation, breaking Ruby 2.7 source installs ([#37607](https://projects.theforeman.org/issues/37607)) + +#### Foreman - Plugin integration +* Plugins are finalized before seeds are executed ([#37503](https://projects.theforeman.org/issues/37503)) + #### Foreman - Proxy gateway * Test Connection' button in 'New HTTP Proxy' returns success with invalid URL ([#36919](https://projects.theforeman.org/issues/36919)) +#### Foreman - Reporting +* Add product host count to 'Subscription - General Report' ([#37756](https://projects.theforeman.org/issues/37756)) + #### Foreman - Settings * The description of a setting Instance color contains additional dot ([#37597](https://projects.theforeman.org/issues/37597)) +* Append domain name setting is not consistently applied everywhere ([#37532](https://projects.theforeman.org/issues/37532)) #### Foreman - Templates * Create a way to refresh CA certificates on hosts that are managed by Katello ([#37601](https://projects.theforeman.org/issues/37601)) -* RHEL registration template ignores host_parm subscription_manager_org ([#37496](https://projects.theforeman.org/issues/37496)) -* Templates - cloned_from reference ([#37059](https://projects.theforeman.org/issues/37059)) -* Template render error when no PXELoader is selected ([#36626](https://projects.theforeman.org/issues/36626)) +* Track original template when cloning templates ([#37059](https://projects.theforeman.org/issues/37059)) #### Foreman - Tests * nic_managed factory can create an IP outside of its subnet ([#37711](https://projects.theforeman.org/issues/37711)) * Report renderer tests fail depending on the libyaml version ([#37613](https://projects.theforeman.org/issues/37613)) * with_temporary_settings test helper doesn't clean up properly ([#37558](https://projects.theforeman.org/issues/37558)) +* Possibility to use selenium remote driver ([#36978](https://projects.theforeman.org/issues/36978)) #### Foreman - Unattended installations * Use SHA512 for root password hashing when no OS is set ([#37614](https://projects.theforeman.org/issues/37614)) * HostCommon.crypt_passwords reencrypts Base64 based passwords for Grub, leading to errors ([#37610](https://projects.theforeman.org/issues/37610)) +* Monitor -&gt; Host statusses shows "Pending Installation" instead of Installed ([#37589](https://projects.theforeman.org/issues/37589)) +* Provisioning Templates or RHEL 9 should have option timesource ([#37581](https://projects.theforeman.org/issues/37581)) +* Improved "EFI local chainloading" on SecureBoot enabled hosts not working for all distribution ([#37562](https://projects.theforeman.org/issues/37562)) +* RHEL registration template ignores host_parm subscription_manager_org ([#37496](https://projects.theforeman.org/issues/37496)) +* Cloudinit default generates invalid yaml output ([#37433](https://projects.theforeman.org/issues/37433)) +* Improve "EFI local chainloading" on SecureBoot enabled hosts ([#37345](https://projects.theforeman.org/issues/37345)) +* Upload facts after host provisioning ([#36886](https://projects.theforeman.org/issues/36886)) +* Template render error when no PXELoader is selected ([#36626](https://projects.theforeman.org/issues/36626)) * Extend Windows support in templates ([#36495](https://projects.theforeman.org/issues/36495)) #### Foreman - Web Interface -* Add button linking to new All Hosts UI ([#37690](https://projects.theforeman.org/issues/37690)) * Show complete hostgroup name in host overview and table ([#37648](https://projects.theforeman.org/issues/37648)) * Tab title missing in tableindexpage ([#37645](https://projects.theforeman.org/issues/37645)) * Pagination doesnt always update between react pages ([#37644](https://projects.theforeman.org/issues/37644)) * Template render error when host has .ics domain name ([#37623](https://projects.theforeman.org/issues/37623)) -* Host details - Fix append domain setting ([#37584](https://projects.theforeman.org/issues/37584)) -* use textarea in host comment edit ([#37582](https://projects.theforeman.org/issues/37582)) * remove space between table buttons ([#37578](https://projects.theforeman.org/issues/37578)) * Foreman Table columns sort is inconsistent ([#37575](https://projects.theforeman.org/issues/37575)) * Cancel build shows notification with host id instead of hostname on the new UI of Red Hat Satellite ([#37556](https://projects.theforeman.org/issues/37556)) -* New All Hosts page ignores pagination url params on first load ([#37485](https://projects.theforeman.org/issues/37485)) -* Add Power Status column to new All Hosts page ([#37478](https://projects.theforeman.org/issues/37478)) -* Extend TableIndexPage and TableHooks with new capabilities for All Hosts page ([#37398](https://projects.theforeman.org/issues/37398)) +* Help page should not link libera chat anymore after the migration to matrix ([#37086](https://projects.theforeman.org/issues/37086)) #### Installer * After an OS version upgrade, the GUI still shows the old/wrong Operating System version ([#37726](https://projects.theforeman.org/issues/37726)) -* Disable port 8443 by default ([#37701](https://projects.theforeman.org/issues/37701)) -* Installler doesn't handle Puppetserver 8 upgrade ([#37686](https://projects.theforeman.org/issues/37686)) -* Correct docroot for Content Proxies's Apache vhost ([#37620](https://projects.theforeman.org/issues/37620)) -* Possibility to set puppet version in gitlab CI ([#37568](https://projects.theforeman.org/issues/37568)) +* Disable port 8443 by default on content proxies ([#37701](https://projects.theforeman.org/issues/37701)) #### Installer - Foreman modules * Pasing --foreman-proxy-content-enable-docker false can leave smart_proxy_container_gateway in an inconsistent state ([#37707](https://projects.theforeman.org/issues/37707)) +* Correct docroot for Content Proxies's Apache vhost ([#37620](https://projects.theforeman.org/issues/37620)) * DNS forwarders aren't validated ([#37604](https://projects.theforeman.org/issues/37604)) #### Installer - foreman-installer script * Add check for ipv6.disable=1 in /proc/cmdline because it's known to break installations ([#37693](https://projects.theforeman.org/issues/37693)) +* Installler doesn't handle Puppetserver 8 upgrade ([#37686](https://projects.theforeman.org/issues/37686)) +* Possibility to set puppet version in gitlab CI ([#37568](https://projects.theforeman.org/issues/37568)) #### Packaging - RPMs * Make foreman-installer-katello pull in foreman-maintain ([#37663](https://projects.theforeman.org/issues/37663)) #### SELinux - Plugins -* Boot disk based Provisioning fails to generate ISO image for instance clietn.example.com: ERF42-8093 [Foreman::Exception]: ISO build failed ([#37497](https://projects.theforeman.org/issues/37497)) +* Boot disk based Provisioning fails to generate ISO image for instance client.example.com: ERF42-8093 [Foreman::Exception]: ISO build failed ([#37497](https://projects.theforeman.org/issues/37497)) -#### Smart Proxy +#### Smart Proxy - BMC * Maximum sessions limit reached on iDRAC using Redfish as BMC provider ([#37486](https://projects.theforeman.org/issues/37486)) #### Smart Proxy - DHCP diff --git a/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md b/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md index 9f8b4400d0..207e473061 100644 --- a/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md +++ b/_includes/manuals/3.12/4.3.7_smartproxy_puppetca.md @@ -17,11 +17,6 @@ Also choose the provider to use, default should be `puppetca_hostname_whitelisti :use_provider: puppetca_hostname_whitelisting ``` -Lastly the Puppet version needs to be specified. Since version 6 the `puppetca_http_api` implementation is used while on earlier versions the `puppetca_puppet_cert` implementation is used. -```yaml -:puppet_version: '6.8.0' -``` - #### puppetca_hostname_whitelisting The `puppetca_hostname_whitelisting` provider directly manages Puppet's `autosign.conf` file. @@ -75,40 +70,8 @@ After deploying the script the Puppet configuration has to be changed to point t autosign = /usr/libexec/foreman-proxy/puppet_sign.rb ``` -#### puppetca_puppet_cert - -**Note** this is used in Puppet 5 and earlier as determined by the `puppet_version` setting in `puppetca.yml`. - -This implementation is used for managing certificates. It uses the `puppet cert` command and typically requires sudo access for the proxy. - -```yaml -:ssldir: /etc/puppetlabs/puppet/ssl -#:puppetca_use_sudo: false -#:sudo_command: /usr/bin/sudo -``` - -The `ssldir` setting is required and can be determined with `puppet config print ssldir`. Puppet AIO defaults to using `/etc/puppetlabs/puppet/ssl`. - -By default sudo is used but can be disabled with `puppetca_use_sudo` setting. The sudo command is dermined via the `PATH` variable or can be explicitly set with the `sudo_command` setting. - -For sudo to work correctly, it must be configured to allow `puppet cert` with NOPASSWD and without requiretty. Under a Puppet AIO installation, configuration should be: - -``` -foreman-proxy ALL = NOPASSWD: /opt/puppetlabs/bin/puppet cert * -Defaults:foreman-proxy !requiretty -``` - -Under a non-AIO Puppet installation: - -``` -foreman-proxy ALL = NOPASSWD: /usr/bin/puppet cert * -Defaults:foreman-proxy !requiretty -``` - #### puppetca_http_api -**Note** this is used in Puppet 6 and newer as determined by the `puppet_version` setting in `puppetca.yml`. - As the name implies, Puppetserver's HTTP API is used to manage certificates. In its configuration file `puppetca_http_api.yml` the connection details are configured: ```yaml