From 7905ee85b1b4395cddaa058c498be4c0006c59a2 Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Thu, 5 Dec 2024 18:10:41 +0200 Subject: [PATCH] Upstreamize VM subscriptions guide --- ...mbly_managing-virt-who-configurations.adoc | 22 +++ ...assembly_overview-of-vm-subscriptions.adoc | 3 + .../assembly_troubleshooting-virt-who.adoc | 7 + guides/common/attributes-titles.adoc | 1 + ...con_deploying-virt-who-configurations.adoc | 10 ++ .../con_managing-virt-who-configurations.adoc | 7 + .../modules/con_troubleshooting-virt-who.adoc | 6 + ...irtual-machine-subscriptions-overview.adoc | 20 +++ ...r-subscriptions-that-require-virt-who.adoc | 10 ++ .../proc_checking-virt-who-status.adoc | 21 +++ ...roc_creating-a-virt-who-configuration.adoc | 130 ++++++++++++++++++ ...a-virt-who-configuration-on-a-capsule.adoc | 40 ++++++ ...irt-who-configuration-on-a-hypervisor.adoc | 46 +++++++ ...nfiguration-on-a-separate-rhel-server.adoc | 72 ++++++++++ ...who-configuration-on-satellite-server.adoc | 17 +++ ...proc_editing-a-virt-who-configuration.adoc | 26 ++++ .../proc_enabling-rhsm-debug-logging.adoc | 26 ++++ ...roc_removing-a-virt-who-configuration.adoc | 16 +++ ...virt-who-does-not-report-to-satellite.adoc | 13 ++ .../modules/ref_troubleshooting-virt-who.adoc | 75 ++++++++++ .../ref_virt-who-configuration-examples.adoc | 99 +++++++++++++ .../ref_virt-who-configuration-overview.adoc | 29 ++++ ...ef_virt-who-troubleshooting-scenarios.adoc | 28 ++++ .../Makefile | 1 + .../common | 1 + .../docinfo.html | 1 + .../docinfo.xml | 15 ++ .../images | 1 + .../master.adoc | 24 ++++ .../upstream_filename_to_satellite_link.json | 1 + 30 files changed, 768 insertions(+) create mode 100644 guides/common/assembly_managing-virt-who-configurations.adoc create mode 100644 guides/common/assembly_overview-of-vm-subscriptions.adoc create mode 100644 guides/common/assembly_troubleshooting-virt-who.adoc create mode 100644 guides/common/modules/con_deploying-virt-who-configurations.adoc create mode 100644 guides/common/modules/con_managing-virt-who-configurations.adoc create mode 100644 guides/common/modules/con_troubleshooting-virt-who.adoc create mode 100644 guides/common/modules/con_virtual-machine-subscriptions-overview.adoc create mode 100644 guides/common/modules/proc_checking-for-subscriptions-that-require-virt-who.adoc create mode 100644 guides/common/modules/proc_checking-virt-who-status.adoc create mode 100644 guides/common/modules/proc_creating-a-virt-who-configuration.adoc create mode 100644 guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc create mode 100644 guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc create mode 100644 guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc create mode 100644 guides/common/modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc create mode 100644 guides/common/modules/proc_editing-a-virt-who-configuration.adoc create mode 100644 guides/common/modules/proc_enabling-rhsm-debug-logging.adoc create mode 100644 guides/common/modules/proc_removing-a-virt-who-configuration.adoc create mode 100644 guides/common/modules/proc_virt-who-does-not-report-to-satellite.adoc create mode 100644 guides/common/modules/ref_troubleshooting-virt-who.adoc create mode 100644 guides/common/modules/ref_virt-who-configuration-examples.adoc create mode 100644 guides/common/modules/ref_virt-who-configuration-overview.adoc create mode 100644 guides/common/modules/ref_virt-who-troubleshooting-scenarios.adoc create mode 100644 guides/doc-Configuring_Virt-Who-VM-Subscriptions/Makefile create mode 120000 guides/doc-Configuring_Virt-Who-VM-Subscriptions/common create mode 120000 guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.html create mode 100644 guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml create mode 120000 guides/doc-Configuring_Virt-Who-VM-Subscriptions/images create mode 100644 guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc diff --git a/guides/common/assembly_managing-virt-who-configurations.adoc b/guides/common/assembly_managing-virt-who-configurations.adoc new file mode 100644 index 00000000000..50af8111ee2 --- /dev/null +++ b/guides/common/assembly_managing-virt-who-configurations.adoc @@ -0,0 +1,22 @@ +include::modules/con_managing-virt-who-configurations.adoc[] + +include::modules/proc_checking-for-subscriptions-that-require-virt-who.adoc[leveloffset=+1] + +include::modules/proc_creating-a-virt-who-configuration.adoc[leveloffset=+1] + +include::modules/ref_virt-who-configuration-examples.adoc[leveloffset=+2] + +include::modules/con_deploying-virt-who-configurations.adoc[leveloffset=+1] + +include::modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc[leveloffset=+2] + +include::modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc[leveloffset=+2] + +include::modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc[leveloffset=+2] + +include::modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc[leveloffset=+2] + +include::modules/proc_editing-a-virt-who-configuration.adoc[leveloffset=+1] + +include::modules/proc_removing-a-virt-who-configuration.adoc[leveloffset=+1] + diff --git a/guides/common/assembly_overview-of-vm-subscriptions.adoc b/guides/common/assembly_overview-of-vm-subscriptions.adoc new file mode 100644 index 00000000000..7724378f447 --- /dev/null +++ b/guides/common/assembly_overview-of-vm-subscriptions.adoc @@ -0,0 +1,3 @@ +include::modules/con_virtual-machine-subscriptions-overview.adoc[] + +include::modules/ref_virt-who-configuration-overview.adoc[leveloffset=+1] diff --git a/guides/common/assembly_troubleshooting-virt-who.adoc b/guides/common/assembly_troubleshooting-virt-who.adoc new file mode 100644 index 00000000000..570aa2de1f4 --- /dev/null +++ b/guides/common/assembly_troubleshooting-virt-who.adoc @@ -0,0 +1,7 @@ +include::modules/con_troubleshooting-virt-who.adoc[] + +include::modules/proc_checking-virt-who-status.adoc[leveloffset=+1] + +include::modules/proc_enabling-rhsm-debug-logging.adoc[leveloffset=+1] + +include::modules/proc_virt-who-does-not-report-to-satellite.adoc[leveloffset=+1] diff --git a/guides/common/attributes-titles.adoc b/guides/common/attributes-titles.adoc index 2d5f1c4dd12..894f8e44d69 100644 --- a/guides/common/attributes-titles.adoc +++ b/guides/common/attributes-titles.adoc @@ -6,6 +6,7 @@ :AppCentricDeploymentDocTitle: Deploying hosts by using application centric approach :ConfiguringLoadBalancerDocTitle: Configuring {SmartProxies} with a load balancer :ConfiguringUserAuthenticationDocTitle: Configuring authentication for {ProjectName} users +:ConfiguringVMSubscriptionsDocTitle: Configuring virt-who for virtual machine subscriptions :ContentManagementDocTitle: Managing content :ConvertingHostRHELDocTitle: Converting a host to RHEL :DeployingAWSDocTitle: Deploying {ProjectName} on Amazon Web Services diff --git a/guides/common/modules/con_deploying-virt-who-configurations.adoc b/guides/common/modules/con_deploying-virt-who-configurations.adoc new file mode 100644 index 00000000000..c417f2700ef --- /dev/null +++ b/guides/common/modules/con_deploying-virt-who-configurations.adoc @@ -0,0 +1,10 @@ +[id="deploying-virt-who-configurations_{context}"] += Deploying virt-who configurations + +After you create a virt-who configuration, you download a script from the {ProjectWebUI} to deploy the configuration. + +The script installs virt-who and creates the local and global virt-who configuration files. + +For {oVirt}, {EL} Virtualization (KVM), and {OpenStack}, you deploy the configuration on the hypervisor specified in the file. + +For VMware vSphere, Microsoft Hyper-V, and Nutanix AHV, you deploy the configuration on {ProjectServer}, {SmartProxyServer}, or on a dedicated {EL} server. diff --git a/guides/common/modules/con_managing-virt-who-configurations.adoc b/guides/common/modules/con_managing-virt-who-configurations.adoc new file mode 100644 index 00000000000..a4bcd2325bf --- /dev/null +++ b/guides/common/modules/con_managing-virt-who-configurations.adoc @@ -0,0 +1,7 @@ += Managing virt-who configurations + +You can check for subscriptions that require a virt-who configuration. + +Then, you create a virt-who configuration and deploy it on a hypervisor or virtualization manager. + +Optionally, you can edit or delete a virt-who configuration. \ No newline at end of file diff --git a/guides/common/modules/con_troubleshooting-virt-who.adoc b/guides/common/modules/con_troubleshooting-virt-who.adoc new file mode 100644 index 00000000000..d0403e1c3e2 --- /dev/null +++ b/guides/common/modules/con_troubleshooting-virt-who.adoc @@ -0,0 +1,6 @@ +[id="troubleshooting-virt-who_{context}"] += Troubleshooting virt-who + +You can troubleshoot virt-who by checking the service status, logs, and by identifying configuration issues. + +For more information, see link:https://docs.redhat.com/en/documentation/subscription_central/1-latest/html/getting_started_with_rhel_system_registration/adv-reg-rhel-config-vm-sub_#virt-who-troubleshooting-methods_[Virt-who troubleshooting methods] and link:https://docs.redhat.com/en/documentation/subscription_central/1-latest/html/getting_started_with_rhel_system_registration/adv-reg-rhel-config-vm-sub_#virt-who-troubleshooting-scenarios_[Virt-who troubleshooting scenarios] in _Getting Started with RHEL System Registration_ in the Subscription Central documentation. \ No newline at end of file diff --git a/guides/common/modules/con_virtual-machine-subscriptions-overview.adoc b/guides/common/modules/con_virtual-machine-subscriptions-overview.adoc new file mode 100644 index 00000000000..e5691de714e --- /dev/null +++ b/guides/common/modules/con_virtual-machine-subscriptions-overview.adoc @@ -0,0 +1,20 @@ +[id="virtual-machine-subscriptions-overview_{context}"] += Virtual machine subscriptions overview + +Virtual machines (VMs) require host-based subscriptions instead of physical subscriptions. +Many host-based subscriptions include entitlements for unlimited VMs. + +You can configure and deploy virt-who on your hypervisors. +virt-who queries the virtualization platform and reports hypervisor and VM information to {Project}. +You can view your subscription usage by using the Subscriptions service on the {RHCloud}. + +You can configure host-based subscriptions for {EL} VMs on the following virtualization platforms: + +* VMware vSphere +* {EL} Virtualization (KVM) +* {KubeVirt} +* {OpenStack} +* {oVirt} +* Microsoft Hyper-V +* Nutanix AHV + diff --git a/guides/common/modules/proc_checking-for-subscriptions-that-require-virt-who.adoc b/guides/common/modules/proc_checking-for-subscriptions-that-require-virt-who.adoc new file mode 100644 index 00000000000..36e3be0f38d --- /dev/null +++ b/guides/common/modules/proc_checking-for-subscriptions-that-require-virt-who.adoc @@ -0,0 +1,10 @@ +[id="checking-for-subscriptions-that-require-virt-who_{context}"] += Checking for subscriptions that require virt-who + +You can check for subscriptions that require virt-who configuration. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Content* > *Subscriptions*. +. Check the *Requires Virt-Who* column of the subscriptions list. +If a tick is displayed, you must configure virt-who to use that subscription. diff --git a/guides/common/modules/proc_checking-virt-who-status.adoc b/guides/common/modules/proc_checking-virt-who-status.adoc new file mode 100644 index 00000000000..cf320e89a9a --- /dev/null +++ b/guides/common/modules/proc_checking-virt-who-status.adoc @@ -0,0 +1,21 @@ +[id="checking-virt-who-status_{context}"] += Checking virt-who status + +You can check the status of virt-who by using the {ProjectWebUI} or the Hammer CLI tool. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Check the *Status* column of each virt-who instance. ++ +The `OK` status indicates that virt-who is successfully connecting to {ProjectServer} and reporting the virtual machines managed by each hypervisor. + +.CLI procedure + +* To list the status of all virt-who instances by using the CLI, enter the following command on {ProjectServer}: ++ +---- +$ hammer virt-who-config list +---- ++ +The output includes the date and time when each virt-who instance reported to {ProjectServer}. \ No newline at end of file diff --git a/guides/common/modules/proc_creating-a-virt-who-configuration.adoc b/guides/common/modules/proc_creating-a-virt-who-configuration.adoc new file mode 100644 index 00000000000..905d2ab0b6a --- /dev/null +++ b/guides/common/modules/proc_creating-a-virt-who-configuration.adoc @@ -0,0 +1,130 @@ +[id="creating-a-virt-who-configuration_{context}"] += Creating a virt-who configuration + +You can create a virt-who configuration by using the {ProjectWebUI} or the Hammer CLI tool. + +The virt-who configuration creates a `virt_who_reporter_[id]` user with the `Virt-who Reporter` role, which provides minimal permissions for virt-who reporting to {ProjectServer}. +This user cannot be manually configured or used to log in to {ProjectServer}. + +Local configuration values are stored in the `/etc/virt-who.d/_conf_name_.conf` file and apply only to the hypervisor or virtualization manager. + +Global configuration values, such as `Interval`, `Enable debugging output`, `HTTP Proxy`, and `Ignore Proxy`, apply to all virt-who configurations on the same server and are overwritten if you deploy a new virt-who configuration on that server. +Global configuration values are stored in the `/etc/sysconfig/virt-who` file. + +.Prerequisites + +* You have imported a subscription manifest that includes a host-based subscription into {ProjectServer}. +* VMware vSphere: You have created a virt-who user with read-only access to all objects in the vCenter Data Center and a non-expiring password on the vCenter Server. +* Microsoft Hyper-V: +** You have enabled remote management on each hypervisor. +** You have created a virt-who user with read-only access and a non-expiring password on each hypervisor. +* {oVirt}, {EL} Virtualization (KVM), {OpenStack}: +** You have registered the hypervisor to {ProjectServer}. +** You have created a virt-who user with read-only access and a non-expiring password on each hypervisor. +* {KubeVirt}: You have created a `kubeconfig` file. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Click *Create Config*. +. Complete the following fields: +* *Name*: Configuration name. +* *Hypervisor Type*: Select one of the following types: +** *VMware vSphere / vCenter (esx)*. +** *Microsoft Hyper-V (hyperv)*. +** *libvirt*: For {oVirt}, {EL} Virtualization (KVM), or {OpenStack}. +** *Container-native virtualization*: For {KubeVirt}. +** *Nutanix AHV (ahv)*. + +* VMware vSphere and Microsoft Hyper-V: +** *Hypervisor Server*: FQDN or IP address. +** *Hypervisor Username*: virt-who user name. +** *Hypervisor Password*: virt-who user password. +The password is encrypted when you deploy the configuration. + +* *Interval*: Virtual machine information reporting interval. + +* *{ProjectServer} FQDN*. +* *Hypervisor ID*: Select *Hostname* or *UUID*. + +. Optional: *Filtering*. Select one of the following options for querying hypervisors: +* *Unlimited* (default): All hypervisors are queried. +* *Whitelist*: Specific hypervisors are included. +* *Blacklist*: Specific hypervisors are excluded. +** *Filter hosts*: Comma-separated list of included hypervisors. +** *Exclude hosts*: Comma-separated list of excluded hypervisors. ++ +-- +Specify the host name or UUID according to the hypervisor ID you selected. + +.Host names + +* You can use wildcards, regular expressions, and special characters in the host name. +* If you use regular expressions, you must escape the backslashes. +* If you use special characters, you must enclose the host name in quotation marks. +-- ++ +* vCenter Server: +** *Filter host parents*: Comma-separated list of included cluster IDs. +** *Exclude host parents*: Comma-separated list of excluded cluster IDs. +For more information, see link:https://access.redhat.com/solutions/5696481[Using the "Filter Host Parents" and "Exclude Host Parents" Attributes with VMware Clusters] in the _Red{nbsp}Hat Knowledgebase_. + +. You can configure the following logging and proxy options: + +* *Enable debugging output*: Enables debug logging for virt-who. +* *HTTP Proxy*. +Example: `http://_proxy.example.com_:3128`. ++ +To use no proxy, leave this field blank; this has the same result as entering `{asterisk}` in the *Ignore Proxy* field. +* *Ignore Proxy*: Comma-separated list of host names, IP addresses, or domains to bypass existing proxy settings. +. {KubeVirt}: Enter the path in the *Path to kubeconfig file* field. +. Nutanix AHV: +* Select *Prism Central* or *Prism Element* from the *Prism Flavor* list. +* Optional: *Enable AHV Debug*: Enables AHV internal debugging. +This option provides additional AHV information when you enable both debugging options. + +. Click *Submit*. + +.CLI procedure + +* On {ProjectServer}, enter the `hammer virt-who-config create` command according to the following example: ++ +[options="nowrap" subs="+quotes"] +---- +$ hammer virt-who-config create \ +--name _My_virt-who_Configuration_ \ +--organizations "_My_Organization_" \ +--interval 720 \ <1> +--filtering-mode none \ <2> +--hypervisor-id hostname \ <3> +--hypervisor-type libvirt \ <4> +--hypervisor-server _{foreman-example-com}_ \ <5> +--hypervisor-username virt_who_user \ <6> +--proxy '_http://proxy.example.com_:3128' \ <7> +--satellite-url _server.example.com_ +---- +-- +<1> Virtual machine information reporting interval, in minutes. +<2> Specify `none` for no filtering of hypervisors for virt-who queries. +Specify `whitelist` or `blacklist` to include or exclude hypervisors for virt-who queries. +<3> Specify `hostname`, `uuid`, or `hwuuid` for the hypervisor ID format. +* You can use `uuid` to avoid duplication if a hypervisor is renamed. ++ +* You can use `hwuuid` for configurations that apply to a virtualization manager instead of an individual hypervisor. ++ +[NOTE] +==== +You cannot change `hwuuid` to another option after virt-who starts running because this might cause duplicate entires in Subscription Manager. +==== + +<4> Specify the hypervisor type: +* {EL} Virtualization (KVM), {oVirt}, or {OpenStack}: `libvirt`. +* VMware vSphere: `esx`. +* Microsoft Hyper-V: `hyperv`. +* Nutanix AHV: `ahv` +<5> Specify the FQDN or IP address of the hypervisor or the vCenter Server. +<6> Specify the name of the virt-who user you created on the hypervisor. ++ +For VMware vSphere or Microsoft Hyper-V, specify the virt-who user password: `--hypervisor-password `. +<7> Optional. +-- \ No newline at end of file diff --git a/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc new file mode 100644 index 00000000000..babb257139b --- /dev/null +++ b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-capsule.adoc @@ -0,0 +1,40 @@ +[id="deploying-a-virt-who-configuration-on-a-capsule_{context}"] += Deploying a virt-who configuration on a {SmartProxyServer} + +For VMware vSphere and Microsoft Hyper-V, you can deploy the virt-who configuration on {SmartProxyServer}. + +Global configuration values apply to all virt-who configurations on the same {SmartProxyServer} and are overwritten if you deploy a new virt-who configuration. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Click a virt-who configuration. +. Click the *Deploy* tab. +. Under *Configuration script*, click *Download the script*. +. Copy the script to {SmartProxyServer}: ++ +[options="nowrap" subs="+quotes"] +---- +$ scp _deploy_virt_who_config_1_.sh root@_{smartproxy-example-com}_: +---- + +. Make the script executable: ++ +[options="nowrap" subs="+quotes"] +---- +$ chmod +x _deploy_virt_who_config_1_.sh +---- + +. Run the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ sh _deploy_virt_who_config_1_.sh +---- + +. After the deployment is complete, delete the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ rm _deploy_virt_who_config_1_ +---- diff --git a/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc new file mode 100644 index 00000000000..4d16212df75 --- /dev/null +++ b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc @@ -0,0 +1,46 @@ +[id="deploying-a-virt-who-configuration-on-a-hypervisor_{context}"] += Deploying a virt-who configuration on a hypervisor or a {SmartProxyServer} + +For {oVirt}, {EL} Virtualization (KVM), and {OpenStack}, you deploy the configuration on the hypervisor specified in the file. + +Global values apply only to this hypervisor. + +.Prerequisites + +* You have registered the hypervisor to {ProjectServer}. +* {oVirt}: You have updated {oVirt} to the latest version so that the minimum virt-who version is available. +virt-who is available by default on {oVirt}, but you cannot update virt-who by using the `rhel-7-server-rhvh-4-rpms` repository. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Click a virt-who configuration. +. Click the *Deploy* tab. +. Under *Configuration script*, click *Download the script*. +. Copy the script to the hypervisor: ++ +[options="nowrap" subs="+quotes"] +---- +$ scp _deploy_virt_who_config_1_.sh root@_hypervisor.example.com_: +---- + +. Make the script executable: ++ +[options="nowrap" subs="+quotes"] +---- +$ chmod +x _deploy_virt_who_config_1_.sh +---- + +. Run the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ sh _deploy_virt_who_config_1_.sh +---- + +. After the deployment is complete, delete the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ rm _deploy_virt_who_config_1_ +---- diff --git a/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc new file mode 100644 index 00000000000..5dad6da72f1 --- /dev/null +++ b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc @@ -0,0 +1,72 @@ +[id="deploying-a-virt-who-configuration-on-a-separate-rhel-server_{context}"] += Deploying a virt-who configuration on a dedicated {EL} server + +For VMware vSphere, Microsoft Hyper-V, and Nutanix AHV, you can deploy the virt-who configuration on a dedicated {EL} server. +The server can be physical or virtual. + +Global configuration values apply to all virt-who configurations on this server and are overwritten if you deploy a new virt-who configuration. + +.Procedure + +. On the {EL} server, install the {ProjectServer} CA certificate: ++ +[options="nowrap" subs="+quotes"] +---- +$ rpm -ivh http://__{server.example.com}__/pub/katello-ca-consumer-latest.noarch.rpm +---- + +. Register the {EL} server to {ProjectServer}: ++ +[options="nowrap" subs="+quotes"] +---- +$ subscription-manager register \ +--org=_organization_label_ \ +--auto-attach +---- + +. Add a TCP port for communication between virt-who and {ProjectServer} to the runtime configuration: ++ +[options="nowrap"] +---- +$ firewall-cmd --add-port="/tcp" <1> +---- +<1> Specify `443` for VMware vCenter and Nutanix AHV. Specify `5985` for Microsoft Hyper-V. + +. Add a TCP port for communication between virt-who and {ProjectServer} to the permanent configuration: ++ +[options="nowrap"] +---- +$ firewall-cmd --add-port="/tcp" --permanent +---- + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Click a virt-who configuration file. +. Click the *Deploy* tab. +. Under *Configuration script*, click *Download the script*. +. Copy the script to the {EL} server: ++ +[options="nowrap" subs="+quotes"] +---- +$ scp _deploy_virt_who_config_1_.sh root@_server.example.com_: +---- + +. Make the script executable: ++ +[options="nowrap" subs="+quotes"] +---- +$ chmod +x _deploy_virt_who_config_1_.sh +---- + +. Run the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ sh _deploy_virt_who_config_1_.sh +---- + +. After the deployment is complete, delete the script: ++ +[options="nowrap" subs="+quotes"] +---- +$ rm _deploy_virt_who_config_1_ +---- diff --git a/guides/common/modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc new file mode 100644 index 00000000000..49de0d7ee75 --- /dev/null +++ b/guides/common/modules/proc_deploying-a-virt-who-configuration-on-satellite-server.adoc @@ -0,0 +1,17 @@ +[id="deploying-a-virt-who-configuration-on-satellite-server_{context}"] += Deploying a virt-who configuration on {ProjectServer} + +For VMware vSphere and Microsoft Hyper-V, you deploy the virt-who configuration on {ProjectServer}. + +Global configuration values apply to all virt-who configurations on {ProjectServer} and are overwritten if you deploy a new virt-who configuration. + +.Prerequisites + +* Microsoft Hyper-V only: You have enabled remote management on the hypervisor. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Click a virt-who configuration. +. Under *Hammer command*, click *Copy to clipboard*. +. Log in to {ProjectServer} and paste the Hammer command into your terminal. diff --git a/guides/common/modules/proc_editing-a-virt-who-configuration.adoc b/guides/common/modules/proc_editing-a-virt-who-configuration.adoc new file mode 100644 index 00000000000..95cb16ee39d --- /dev/null +++ b/guides/common/modules/proc_editing-a-virt-who-configuration.adoc @@ -0,0 +1,26 @@ +[id="editing-a-virt-who-configuration_{context}"] += Editing a virt-who configuration + +You can edit a virt-who configuration by using either the {ProjectWebUI} or the Hammer CLI. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Select *Edit* in the *Actions* column of a virt-who configuration. +. Edit the fields and then click *Submit*. +. Deploy the modified virt-who configuration. + +[id="cli-modifying-virt-who-configuration_{context}"] +.CLI procedure + +. On {ProjectServer}, use the `hammer virt-who-config update` command to edit the virt-who configuration according to the following example: ++ +[options="nowrap" subs="+quotes,verbatim"] +---- +$ hammer virt-who-config update \ +--name _My_virt-who_Configuration_ \ +--new-name _My_new_virt-who_Configuration_ \ +--interval 1440 +---- + +. Deploy the modified virt-who configuration. diff --git a/guides/common/modules/proc_enabling-rhsm-debug-logging.adoc b/guides/common/modules/proc_enabling-rhsm-debug-logging.adoc new file mode 100644 index 00000000000..e10a7a98707 --- /dev/null +++ b/guides/common/modules/proc_enabling-rhsm-debug-logging.adoc @@ -0,0 +1,26 @@ +[id="enabling-rhasm-debug logging_{context}"] += Enabling debug logging + +You can enable debug logging for the `/var/log/rhsm/rhsm.log` file by using the {ProjectWebUI} or the Hammer CLI tool. + +After you resolve the problem, you must disable debug logging and redeploy the virt-who configuration. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Select *Edit* in the *Actions* column of a virt-who configuration. +. Select *Enable debugging output*. +. Click *Submit*. +. Redeploy the virt-who configuration on the target host. + +.CLI procedure + +. On {ProjectServer}, run the `hammer virt-who-config update` command with the debug option: ++ +[options="nowrap" subs="+quotes"] +---- +$ hammer virt-who-config update \ +--debug true +---- + +. Redeploy the virt-who configuration on the target host. diff --git a/guides/common/modules/proc_removing-a-virt-who-configuration.adoc b/guides/common/modules/proc_removing-a-virt-who-configuration.adoc new file mode 100644 index 00000000000..e9b248c85d9 --- /dev/null +++ b/guides/common/modules/proc_removing-a-virt-who-configuration.adoc @@ -0,0 +1,16 @@ +[id="removing-an-existing-virt-who-configuration_{context}"] += Removing a virt-who configuration + +You can remove a virt-who configuration by deleting the configuration in the {ProjectWebUI} and then by deleting the configuration file from the hypervisor or the virtualization manager. + +.Procedure + +. In the {ProjectWebUI}, navigate to *Infrastructure* > *Virt-who Configurations*. +. Select *Delete* from the *Actions* column of the virt-who configuration. +. On the hypervisor or virtualization manager, remove the configuration file by running the following command: ++ +[options="nowrap" subs="+quotes"] ++ +---- +$ rm /etc/virt-who.d/_conf_name_.conf +---- diff --git a/guides/common/modules/proc_virt-who-does-not-report-to-satellite.adoc b/guides/common/modules/proc_virt-who-does-not-report-to-satellite.adoc new file mode 100644 index 00000000000..f8dad803972 --- /dev/null +++ b/guides/common/modules/proc_virt-who-does-not-report-to-satellite.adoc @@ -0,0 +1,13 @@ +[id="virt-who-does-not-report-to-satellite_{context}"] += virt-who does not report to {ProjectServer} + +virt-who might not report to {ProjectServer} if {ProjectServer} is configured to use a proxy server in `rhsm.conf` while virt-who is configured not to use a proxy server in `/etc/sysconfig/virt-who`. + +The virt-who setting is ignored by the Subscription Manager. As a result, virt-who attempts to connect to {ProjectServer} through a proxy server and fails. + +To work around this problem, add the following parameter to the `/etc/rhsm/rhsm.conf` file: + +[source,text] +---- +no_proxy = server.example.com +---- diff --git a/guides/common/modules/ref_troubleshooting-virt-who.adoc b/guides/common/modules/ref_troubleshooting-virt-who.adoc new file mode 100644 index 00000000000..f5bc91478ec --- /dev/null +++ b/guides/common/modules/ref_troubleshooting-virt-who.adoc @@ -0,0 +1,75 @@ +[id="virt-who-troubleshooting-methods_{context}"] += Virt-who troubleshooting methods + +.Identifying issues when using multiple virt-who configuration files + +If you have multiple virt-who configuration files on one server, move one file at a time to a different directory while testing after each file move. +If the issue no longer occurs, the cause is associated with the most recently moved file. +After you have resolved the issue, return the virt-who configuration files to their original location. + +Alternatively, you can test an individual file after moving it by using the `--config` option to specify its location. For example: + +[options="nowrap" subs="+quotes,verbatim"] +---- +$ virt-who --debug --one-shot --config /tmp/_conf_name_.conf +---- + +.Identifying duplicate hypervisors + +Duplicate hypervisors can cause subscription and entitlement errors. Enter the following commands to check for duplicate hypervisors: + +[options="nowrap" subs="+quotes,verbatim"] +---- +# systemctl stop virt-who +# virt-who -op >/tmp/virt-who.json +# systemctl start virt-who +# cat /tmp/virt-who.json | json_reformat | grep name | sort | uniq -c | sort -nr | head -n10 + 3 "name": "localhost" + 1 "name": "rhel1.example.com" + 1 "name": "rhel2.example.com" + 1 "name": "rhel3.example.com" + 1 "name": "rhel4.example.com" + 1 "name": "rhvh1.example.com" + 1 "name": "rhvh2.example.com" + 1 "name": "rhvh3.example.com" + 1 "name": "rhvh4.example.com" + 1 "name": "rhvh5.example.com" +---- + +In this example, three hypervisors have the same FQDN (`localhost`), and must be corrected to use unique FQDNs. + +.Identifying duplicate virtual machines + +Enter the following commands to check for duplicate virtual machines: + +[options="nowrap" subs="+quotes,verbatim"] +---- +# systemctl stop virt-who +# virt-who -op >/tmp/virt-who.json +# systemctl start virt-who +# cat /tmp/virt-who.json | json_reformat | grep "guestId" | sort | uniq -c | sort -nr | head -n10 +---- + +.Checking the number of hypervisors + +Enter the following commands to check the number of hypervisors virt-who currently reports: + +[options="nowrap" subs="+quotes,verbatim"] +---- +# systemctl stop virt-who +# virt-who -op >/tmp/virt-who.json +# systemctl start virt-who +# cat /tmp/virt-who.json | json_reformat | grep name | sort | uniq -c | wc -l +---- + +.Checking the number of virtual machines + +Enter the following commands to check the number of virtual machines that virt-who currently reports: + +[options="nowrap" subs="+quotes,verbatim"] +---- +# systemctl stop virt-who +# virt-who -op >/tmp/virt-who.json +# systemctl start virt-who +# cat /tmp/virt-who.json | json_reformat | grep "guestId" | sort | uniq -c | wc -l +---- diff --git a/guides/common/modules/ref_virt-who-configuration-examples.adoc b/guides/common/modules/ref_virt-who-configuration-examples.adoc new file mode 100644 index 00000000000..43cabbd3f71 --- /dev/null +++ b/guides/common/modules/ref_virt-who-configuration-examples.adoc @@ -0,0 +1,99 @@ +[id="virt-who-configuration-examples_{context}"] += Virt-who configuration examples + +You configure virt-who in a file that specifies details such as the virtualization type and the hypervisor or virtualization manager to query. + +[IMPORTANT] +==== +The `rhevm` and `xen` hypervisors are not supported. + +The `kubevirt` hypervisor is a Technology Preview. +==== + +.Generic example + +[source,text] +---- +type=libvirt <1> +hypervisor_id=hostname +owner=Default_Organization +env=Library +server=server.example.com +username=virt_who_user <2> +encrypted_password=33di3ksskd +rhsm_hostname=server.example.com +rhsm_username=virt_who_reporter_1 <3> +rhsm_encrypted_password=$user_password +rhsm_prefix=/rhsm +---- +<1> Hypervisor type. +<2> Read-only user that you create on the hypervisor before configuring virt-who. +<3> Automatically generated user that has permissions for virt-who to report to {ProjectServer}. + +.{OpenStack} example + +[source,text] +---- +type=libvirt +hypervisor_id=hostname +owner=ORG +env=Library +server=qemu:///system <==== +username=virt-who-user +encrypted_password=33di3ksskd +rhsm_hostname=server.example.com +rhsm_username=virt_who_reporter_1 +rhsm_encrypted_password=23233dj3j3k +rhsm_prefix=/rhsm +---- + +.KVM example + +[source,text] +---- +type=libvirt +hypervisor_id=hostname +owner=gss +env=Library +server=qemu+ssh://root@libvirt.example.com/system +username=root +encrypted_password=33di3ksskd +rhsm_hostname=server.example.com +rhsm_username=virt_who_reporter_1 +rhsm_encrypted_password=23233dj3j3k +rhsm_prefix=/rhsm +---- + +.vCenter Server example + +[source,text] +---- +type=esx +hypervisor_id=hostname +owner=gss +env=Library +server=vcenter.example.com +username=username_vcenter@example.com +encrypted_password=33di3ksskd +rhsm_hostname=server.example.com +rhsm_username=virt_who_reporter_1 +rhsm_encrypted_password=23233dj3j3k +rhsm_prefix=/rhsm +---- + +.Nutanix AHV example + +[source,text] +---- +type=ahv +server=192.0.2.0 +username= +encrypted_password=33di3ksskd +owner=ORG +hypervisor_id=hostname +prism_central=true +rhsm_hostname=server.example.com +rhsm_username=virt_who_reporter_1 +rhsm_encrypted_password=23233dj3j3k +rhsm_prefix=/rhsm +---- diff --git a/guides/common/modules/ref_virt-who-configuration-overview.adoc b/guides/common/modules/ref_virt-who-configuration-overview.adoc new file mode 100644 index 00000000000..30066dc4d4e --- /dev/null +++ b/guides/common/modules/ref_virt-who-configuration-overview.adoc @@ -0,0 +1,29 @@ +[id="virt-who-configuration-overview_{context}"] += virt-who configuration overview + +You install and configure virt-who by preparing your environment and then creating and deploying a virt-who configuration. + +.Preparing your environment + +* Import a subscription manifest that includes a host-based subscription into {ProjectServer}. +* Register each hypervisor to {ProjectServer}. +* Create a virt-who user with read-only access and a non-expiring password on each hypervisor. +The virt-who user retrieves a list of virtual machines and reports them to {ProjectServer}. +* Microsoft Hyper-V: Enable remote management on each hypervisor. + +.Procedure + +. Create a virt-who configuration by using the {ProjectWebUI} or the Hammer CLI tool. +. Deploy the virt-who configuration by downloading a script from the {ProjectWebUI} and running the script on each hypervisor or target host. + +.Next steps +* Edit the system purpose attributes of your host. +For more information, see {ManagingHostsDocURL}Editing_the_System_Purpose_of_a_Host_managing-hosts[Editing the system purpose of a host] in _{ManagingHostsDocTitle}_. +* Create activation keys for your host. +For more information, see {ContentManagementDocURL}Managing_Activation_Keys_content-management[Managing activation keys] in _{ContentManagementDocTitle}_. +ifdef::satellite[] +* In a connected environment, configure the {Project} inventory upload plugin to upload your inventory to {RHCloud}. +For more information, see {RHDocsBaseURL}subscription_central/1-latest/html/getting_started_with_the_subscriptions_service/proc-installing-satellite-inventory-upload-plugin_assembly-setting-up-subscriptionwatch-ctxt[Installing the Satellite inventory upload plugin] in _Getting Started with the Subscriptions Service_. +endif::[] +* Associate the virtual machines with {Project}. +For more information, see {ManagingHostsDocURL}Associating_a_Virtual_Machine_from_a_Hypervisor_managing-hosts[Associating a virtual machine with {Project} from a hypervisor] in _{ManagingHostsDocTitle}_.. \ No newline at end of file diff --git a/guides/common/modules/ref_virt-who-troubleshooting-scenarios.adoc b/guides/common/modules/ref_virt-who-troubleshooting-scenarios.adoc new file mode 100644 index 00000000000..52e27726c40 --- /dev/null +++ b/guides/common/modules/ref_virt-who-troubleshooting-scenarios.adoc @@ -0,0 +1,28 @@ +[id="virt-who-troubleshooting-scenarios_{context}"] += virt-who troubleshooting scenarios + +.Virt-who fails to connect to the virtualization platform + +If virt-who fails to connect to the hypervisor or virtualization manager, check the Red{nbsp}Hat Subscription{nbsp}Manager log file `/var/log/rhsm/rhsm.log`. If you find the message `No route to host`, the hypervisor might be listening on the wrong port. In this case, modify the virt-who configuration and append the correct port number to the *Hypervisor Server* value. + +You must redeploy the virt-who configuration after modifying it. + +.Virt-who fails to connect to the virtualization platform through an HTTP proxy on the local network + +If virt-who cannot connect to the hypervisor or virtualization manager through an HTTP proxy, either configure the proxy to allow local traffic to pass through, or modify the virt-who configuration to use no proxy. + +You must redeploy the virt-who configuration after modifying it. + +.Virt-who fails to report back the host-guest mapping to {ProjectServer} + +Virt-who fails to report back the host-guest mapping to {ProjectServer} in the following circumstances. + +. virt-who is configured and deployed on {ProjectServer}. +. The `rhsm.conf` file of {ProjectServer} is configured to use a proxy server to talk to subscription.rhsm.redhat.com and cdn.redhat.com. +. The `no_proxy=*` setting in `/etc/sysconfig/virt-who` is present but being ignored by subscription-manager, and virt-who attempts to connect back to {ProjectServer} through a proxy server but fails. + +In this case, add the following parameter to the `/etc/rhsm/rhsm.conf` file. + +---- +no_proxy = server.example.com +---- diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/Makefile b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/Makefile new file mode 100644 index 00000000000..dd1e5be8557 --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/Makefile @@ -0,0 +1 @@ +include ../common/Makefile diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/common b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/common new file mode 120000 index 00000000000..60d3b0a6a8f --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/common @@ -0,0 +1 @@ +../common \ No newline at end of file diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.html b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.html new file mode 120000 index 00000000000..e037c37244a --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.html @@ -0,0 +1 @@ +../common/docinfo.html \ No newline at end of file diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml new file mode 100644 index 00000000000..eb6108eefe2 --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml @@ -0,0 +1,15 @@ +Configuring virt-who for virtual machine subscriptions +{ProjectName} +{ProjectVersion} +Tracking the usage of your host-based subscriptions + + Configure virt-who for host-based subscriptions to track subscription usage in the {RHCloud}. + + + + {ProjectName} + Documentation Team + satellite-doc-list@redhat.com + + + diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/images b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/images new file mode 120000 index 00000000000..ac7700aa2af --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/images @@ -0,0 +1 @@ +../common/images/ \ No newline at end of file diff --git a/guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc new file mode 100644 index 00000000000..83c10b0cce9 --- /dev/null +++ b/guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc @@ -0,0 +1,24 @@ +include::common/attributes.adoc[] +include::common/header.adoc[] +:context: virt-who-vm-subs +:virt-who-vm-subs: +:ProductName: {ProjectServer} + += {ConfiguringVMSubscriptionsDocTitle} + +// Render only for relevant and finished contexts +ifdef::HideDocumentOnStable,foreman-deb,satellite[] +include::common/modules/snip_guide-not-ready.adoc[] +endif::[] +ifndef::HideDocumentOnStable,foreman-deb,satellite[] + +ifdef::satellite[] +include::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1] +endif::[] + +include::common/assembly_overview-of-vm-subscriptions.adoc[leveloffset=+1] + +include::common/assembly_managing-virt-who-configurations.adoc[leveloffset=+1] + +include::common/assembly_troubleshooting-virt-who.adoc[leveloffset=+1] + diff --git a/guides/upstream_filename_to_satellite_link.json b/guides/upstream_filename_to_satellite_link.json index 30306b62e40..12d037f19ee 100644 --- a/guides/upstream_filename_to_satellite_link.json +++ b/guides/upstream_filename_to_satellite_link.json @@ -2,6 +2,7 @@ "build/Administering_Project/index-satellite.html": "administering_red_hat_satellite", "build/Configuring_Load_Balancer/index-satellite.html": "configuring_capsules_with_a_load_balancer", "build/Configuring_User_Authentication/index-satellite.html": "configuring_authentication_for_red_hat_satellite_users", + "build/Configuring_Virtual_Machine_Subscriptions/index-satellite.html": "configuring_virtual_machine_subscriptions", "build/Deploying_Project_on_AWS/index-satellite.html": "deploying_red_hat_satellite_on_amazon_web_services", "build/Installing_Proxy/index-satellite.html": "installing_capsule_server", "build/Installing_Server/index-satellite.html": "installing_satellite_server_in_a_connected_network_environment",