Configs

>>>

GET /foreman_virt_who_configure/api/v2/configs
List of virt-who configurations

GET /foreman_virt_who_configure/api/v2/organizations/:organization_id/configs
List of virt-who configurations per organization

Examples

GET /foreman_virt_who_configure/api/configs
200
{
  "total": 3,
  "subtotal": 3,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [
    {
      "name": "my vmware",
      "interval": 120,
      "organization_id": 447626467,
      "whitelist": "a,b",
      "blacklist": null,
      "hypervisor_id": "hostname",
      "hypervisor_type": "esx",
      "hypervisor_server": "vmware.example.com",
      "hypervisor_username": "root",
      "debug": false,
      "satellite_url": "foreman.example.com",
      "no_proxy": null,
      "status": "unknown",
      "last_report_at": null,
      "out_of_date_at": null,
      "filter_host_parents": null,
      "exclude_host_parents": null,
      "kubeconfig_path": null,
      "prism_flavor": null,
      "ahv_internal_debug": null,
      "filtering_mode": 1,
      "id": 27,
      "http_proxy": {
        "id": 1022235412,
        "name": "test",
        "url": "http://test.com"
      },
      "proxy": "http://test.com"
    },
    {
      "name": "config 27",
      "interval": 120,
      "organization_id": 447626468,
      "whitelist": null,
      "blacklist": null,
      "hypervisor_id": "hostname",
      "hypervisor_type": "esx",
      "hypervisor_server": "vmware.example.com",
      "hypervisor_username": "root",
      "debug": false,
      "satellite_url": "foreman.example.com",
      "no_proxy": null,
      "status": "out_of_date",
      "last_report_at": "2024-05-23 17:43:53 UTC",
      "out_of_date_at": "2024-05-23 19:43:53 UTC",
      "filter_host_parents": null,
      "exclude_host_parents": null,
      "kubeconfig_path": null,
      "prism_flavor": null,
      "ahv_internal_debug": null,
      "filtering_mode": 0,
      "id": 28,
      "http_proxy": null
    },
    {
      "name": "config 28",
      "interval": 120,
      "organization_id": 447626469,
      "whitelist": null,
      "blacklist": null,
      "hypervisor_id": "hostname",
      "hypervisor_type": "esx",
      "hypervisor_server": "vmware.example.com",
      "hypervisor_username": "root",
      "debug": false,
      "satellite_url": "foreman.example.com",
      "no_proxy": null,
      "status": "ok",
      "last_report_at": "2024-05-23 19:43:53 UTC",
      "out_of_date_at": "2024-05-23 21:43:53 UTC",
      "filter_host_parents": null,
      "exclude_host_parents": null,
      "kubeconfig_path": null,
      "prism_flavor": null,
      "ahv_internal_debug": null,
      "filtering_mode": 0,
      "id": 29,
      "http_proxy": null
    }
  ]
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
search
optional

filter results

Validations:

  • String
order
optional

Sort and order by a searchable field, e.g. '<field> DESC'

Validations:

  • String
page
optional

Page number, starting at 1

Validations:

  • Must be a number.
per_page
optional

Number of results per page to return, 'all' to return all results

Validations:

  • Must match regular expression /\A([1-9]\d*|all)\Z$/.
>>>

GET /foreman_virt_who_configure/api/v2/configs/:id
Show a virt-who configuration

Examples

GET /foreman_virt_who_configure/api/configs/20
200
{
  "name": "config 22",
  "interval": 120,
  "organization_id": 447626459,
  "whitelist": null,
  "blacklist": null,
  "hypervisor_id": "hostname",
  "hypervisor_type": "esx",
  "hypervisor_server": "vmware.example.com",
  "hypervisor_username": "root",
  "debug": false,
  "satellite_url": "foreman.example.com",
  "no_proxy": null,
  "status": "ok",
  "last_report_at": "2024-05-23 19:43:52 UTC",
  "out_of_date_at": "2024-05-23 21:43:52 UTC",
  "filter_host_parents": null,
  "exclude_host_parents": null,
  "kubeconfig_path": null,
  "prism_flavor": null,
  "ahv_internal_debug": null,
  "filtering_mode": 0,
  "id": 20,
  "http_proxy": null
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
id
required

Validations:

  • string from 2 to 128 characters containing only alphanumeric characters, space, '_', '-' with no leading or trailing space..
>>>

GET /foreman_virt_who_configure/api/v2/configs/:id/deploy_script
Renders a deploy script for the specified virt-who configuration

Examples

GET /foreman_virt_who_configure/api/configs/31/deploy_script.sh
200
#!/bin/bash
heading() {
  echo -e "\n== $1 =="
}

step() {
  step_count=5
  heading "[$1/$step_count] $2"
}

version_lte() {
  [ "$1" = "`echo -e "$1\n$2" | sort -V | head -n1`" ]
}

version_lt() {
  [ "$1" = "$2" ] && return 1 || version_lte $1 $2
}

verify_minimal_version() {
  minimal_version=0.24.2
  installed_version=`rpm -q --queryformat '%{VERSION}' virt-who`

  if version_lt $installed_version $minimal_version; then
    echo "virt-who $installed_version does not meet minimum requirements, please make sure this host is properly subscribed and has access to katello-host-tools repository, minimal virt-who version is $minimal_version"
    return 1
  else
    return 0
  fi
}

result_code=0

compose_install_command() {
  $1 packages unlock
  $1 advanced procedure run packages-install --packages virt-who --assumeyes || result_code=$(($result_code|32))
  $1 packages lock
}

install_virt_who() {
  if `rpm -q satellite-maintain > /dev/null`; then
    compose_install_command satellite-maintain
  elif `rpm -q rubygem-foreman_maintain > /dev/null`; then
    compose_install_command foreman-maintain
  else
    yum install -y virt-who || result_code=$(($result_code|32))
  fi
}

step 1 "Installing virt-who"
install_virt_who

if verify_minimal_version; then
  step 2 "Encrypting password"
  cr_password=$(virt-who-password --password $(echo Y2hhbmdlbWU=|base64 -d) 2> /dev/null)
  user_password=$(virt-who-password --password 'tsdd7U42PzGD63Ay' 2> /dev/null)

  step 3 "Creating virt-who configuration"
  cat > /etc/virt-who.d/virt-who-config-31.conf << EOF
### This configuration file is managed via the virt-who configure plugin
### manual edits will be deleted.
[virt-who-config-31]
type=esx
hypervisor_id=hostname
owner=org33

server=vmware.example.com
username=root
encrypted_password=$cr_password
rhsm_hostname=foreman.example.com
rhsm_username=virt_who_reporter_31
rhsm_encrypted_password=$user_password
rhsm_prefix=/rhsm
EOF
  if [ $? -ne 0 ]; then result_code=$(($result_code|2)); fi

  step 4 "Creating sysconfig virt-who configuration"
  cat > /etc/virt-who.conf << EOF
### This configuration file is managed via the virt-who configure plugin
### manual edits will be deleted.
[global]
debug=0
interval=7200
oneshot=False

[system_environment]
EOF
  if [ $? -ne 0 ]; then result_code=$(($result_code|4)); fi

  step 5 "Enabling and restarting the virt-who service"
  systemctl enable virt-who || result_code=$(($result_code|8))
  systemctl restart virt-who || result_code=$(($result_code|16))
else
  result_code=$(($result_code|1))
fi

heading "Finished"
if [ $result_code -ne 0 ]; then
  echo "There were some errors during configuration:"
  [ $(($result_code&0)) -ge 1 ] && echo 'Success'
  [ $(($result_code&1)) -ge 1 ] && echo 'Newer version of virt-who is required, minimum version is 0.24.2'
  [ $(($result_code&2)) -ge 1 ] && echo 'Unable to create virt-who config file'
  [ $(($result_code&4)) -ge 1 ] && echo 'Unable to create sysconfig file'
  [ $(($result_code&8)) -ge 1 ] && echo 'Unable to enable virt-who service using systemctl'
  [ $(($result_code&16)) -ge 1 ] && echo 'Unable to start virt-who service, please see virt-who logs for more details'
  [ $(($result_code&32)) -ge 1 ] && echo 'Unable to install virt-who package, make sure the host is properly subscribed and has access to katello-host-tools repository'
else
  echo "Finished successfully"
fi

exit $result_code

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
id
required

Validations:

  • string from 2 to 128 characters containing only alphanumeric characters, space, '_', '-' with no leading or trailing space..
>>>

POST /foreman_virt_who_configure/api/v2/configs
Create a virt-who configuration

Examples

POST /foreman_virt_who_configure/api/configs
{
  "foreman_virt_who_configure_config": {
    "name": "my new config",
    "filtering_mode": 0,
    "hypervisor_id": "uuid",
    "hypervisor_type": "kubevirt",
    "satellite_url": "foreman.example.com",
    "organization_id": 447626466
  },
  "config": {}
}
422
{
  "error": {
    "id": null,
    "errors": {
      "kubeconfig_path": [
        "can't be blank"
      ]
    },
    "full_messages": [
      "Kubeconfig path can't be blank"
    ]
  }
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
foreman_virt_who_configure_config
required

Validations:

  • Hash
foreman_virt_who_configure_config[name]
required

Configuration name

Validations:

  • String
foreman_virt_who_configure_config[interval]
required

Configuration interval in minutes

Validations:

  • Must be one of: 60, 120, 240, 480, 720, 1440, 2880, 4320.
foreman_virt_who_configure_config[filtering_mode]
required

Hypervisor filtering mode, 0 means no filtering, 1 means whitelist, 2 means blacklist

Validations:

  • Must be one of: 0, 1, 2.
foreman_virt_who_configure_config[whitelist]
optional , nil allowed

Hypervisor whitelist, applicable only when filtering mode is set to 1. Wildcards and regular expressions are supported, multiple records must be separated by comma.

Validations:

  • String
foreman_virt_who_configure_config[blacklist]
optional , nil allowed

Hypervisor blacklist, applicable only when filtering mode is set to 2. Wildcards and regular expressions are supported, multiple records must be separated by comma.

Validations:

  • String
foreman_virt_who_configure_config[filter_host_parents]
optional , nil allowed

Applicable only for esx provider type. Only hosts which parent (usually ComputeResource) name is specified in comma-separated list in this option will be reported. Wildcards and regular expressions are supported, multiple records must be separated by comma. Put the value into the double-quotes if it contains special characters like comma. All new line characters will be removed in resulting configuration file, white spaces are removed from beginning and end.

Validations:

  • String
foreman_virt_who_configure_config[exclude_host_parents]
optional , nil allowed

Applicable only for esx provider type. Hosts which parent (usually ComputeResource) name is specified in comma-separated list in this option will NOT be reported. Wildcards and regular expressions are supported, multiple records must be separated by comma. Put the value into the double-quotes if it contains special characters like comma. All new line characters will be removed in resulting configuration file, white spaces are removed from beginning and end.

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_id]
required

Specifies how the hypervisor will be identified.

Validations:

  • Must be one of: hostname, uuid, hwuuid.
foreman_virt_who_configure_config[hypervisor_type]
required

Hypervisor type

Validations:

  • Must be one of: esx, hyperv, libvirt, kubevirt, ahv.
foreman_virt_who_configure_config[hypervisor_server]
optional , nil allowed

Fully qualified host name or IP address of the hypervisor

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_username]
optional , nil allowed

Account name by which virt-who is to connect to the hypervisor.

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_password]
optional , nil allowed

Hypervisor password, required for all hypervisor types except for libvirt/kubevirt.

Validations:

  • String
foreman_virt_who_configure_config[satellite_url]
required

Foreman server FQDN

Validations:

  • String
foreman_virt_who_configure_config[debug]
optional , nil allowed

Enable debugging output

Validations:

  • Must be one of: true, false, 1, 0.
foreman_virt_who_configure_config[kubeconfig_path]
optional , nil allowed

Configuration file containing details about how to connect to the cluster and authentication details.

Validations:

  • String
foreman_virt_who_configure_config[http_proxy_id]
optional , nil allowed

HTTP proxy that should be used for communication between the server on which virt-who is running and the hypervisors and virtualization managers.

Validations:

  • Integer
foreman_virt_who_configure_config[no_proxy]
optional , nil allowed

Ignore proxy. A comma-separated list of hostnames or domains or ip addresses to ignore proxy settings for. Optionally this may be set to * to bypass proxy settings for all hostnames domains or ip addresses.

Validations:

  • String
foreman_virt_who_configure_config[organization_id]
required

Organization of the virt-who configuration

Validations:

  • Integer
foreman_virt_who_configure_config[prism_flavor]
optional , nil allowed

Select the Prism flavor you are connecting to

Validations:

  • Must be one of: central, element.
foreman_virt_who_configure_config[ahv_internal_debug]
optional , nil allowed

Option Enable debugging output is required to enable AHV internal debug. It provides extra AHV debug information when both options are enabled

Validations:

  • Must be one of: true, false, 1, 0.
>>>

PUT /foreman_virt_who_configure/api/v2/configs/:id
Update a virt-who configuration

Examples

PUT /foreman_virt_who_configure/api/configs/23
{
  "foreman_virt_who_configure_config": {
    "name": "updated",
    "interval": 240,
    "hypervisor_password": "new_pass"
  },
  "config": {}
}
200
{
  "name": "updated",
  "interval": 240,
  "organization_id": 447626462,
  "whitelist": null,
  "blacklist": null,
  "hypervisor_id": "hostname",
  "hypervisor_type": "esx",
  "hypervisor_server": "vmware.example.com",
  "hypervisor_username": "root",
  "debug": false,
  "satellite_url": "foreman.example.com",
  "no_proxy": null,
  "status": "ok",
  "last_report_at": "2024-05-23 19:43:52 UTC",
  "out_of_date_at": "2024-05-23 21:43:52 UTC",
  "filter_host_parents": null,
  "exclude_host_parents": null,
  "kubeconfig_path": null,
  "prism_flavor": null,
  "ahv_internal_debug": null,
  "filtering_mode": 0,
  "id": 23,
  "http_proxy": null
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
id
required

Configuration numeric identifier

Validations:

  • Must be a number.
foreman_virt_who_configure_config
required

Validations:

  • Hash
foreman_virt_who_configure_config[name]
optional

Configuration name

Validations:

  • String
foreman_virt_who_configure_config[interval]
optional

Configuration interval in minutes

Validations:

  • Must be one of: 60, 120, 240, 480, 720, 1440, 2880, 4320.
foreman_virt_who_configure_config[filtering_mode]
optional

Hypervisor filtering mode, 0 means no filtering, 1 means whitelist, 2 means blacklist

Validations:

  • Must be one of: 0, 1, 2.
foreman_virt_who_configure_config[whitelist]
optional , nil allowed

Hypervisor whitelist, applicable only when filtering mode is set to 1. Wildcards and regular expressions are supported, multiple records must be separated by comma.

Validations:

  • String
foreman_virt_who_configure_config[blacklist]
optional , nil allowed

Hypervisor blacklist, applicable only when filtering mode is set to 2. Wildcards and regular expressions are supported, multiple records must be separated by comma.

Validations:

  • String
foreman_virt_who_configure_config[filter_host_parents]
optional , nil allowed

Applicable only for esx provider type. Only hosts which parent (usually ComputeResource) name is specified in comma-separated list in this option will be reported. Wildcards and regular expressions are supported, multiple records must be separated by comma. Put the value into the double-quotes if it contains special characters like comma. All new line characters will be removed in resulting configuration file, white spaces are removed from beginning and end.

Validations:

  • String
foreman_virt_who_configure_config[exclude_host_parents]
optional , nil allowed

Applicable only for esx provider type. Hosts which parent (usually ComputeResource) name is specified in comma-separated list in this option will NOT be reported. Wildcards and regular expressions are supported, multiple records must be separated by comma. Put the value into the double-quotes if it contains special characters like comma. All new line characters will be removed in resulting configuration file, white spaces are removed from beginning and end.

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_id]
optional

Specifies how the hypervisor will be identified.

Validations:

  • Must be one of: hostname, uuid, hwuuid.
foreman_virt_who_configure_config[hypervisor_type]
optional

Hypervisor type

Validations:

  • Must be one of: esx, hyperv, libvirt, kubevirt, ahv.
foreman_virt_who_configure_config[hypervisor_server]
optional , nil allowed

Fully qualified host name or IP address of the hypervisor

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_username]
optional , nil allowed

Account name by which virt-who is to connect to the hypervisor.

Validations:

  • String
foreman_virt_who_configure_config[hypervisor_password]
optional , nil allowed

Hypervisor password, required for all hypervisor types except for libvirt/kubevirt.

Validations:

  • String
foreman_virt_who_configure_config[satellite_url]
optional

Foreman server FQDN

Validations:

  • String
foreman_virt_who_configure_config[debug]
optional , nil allowed

Enable debugging output

Validations:

  • Must be one of: true, false, 1, 0.
foreman_virt_who_configure_config[kubeconfig_path]
optional , nil allowed

Configuration file containing details about how to connect to the cluster and authentication details.

Validations:

  • String
foreman_virt_who_configure_config[http_proxy_id]
optional , nil allowed

HTTP proxy that should be used for communication between the server on which virt-who is running and the hypervisors and virtualization managers.

Validations:

  • Integer
foreman_virt_who_configure_config[no_proxy]
optional , nil allowed

Ignore proxy. A comma-separated list of hostnames or domains or ip addresses to ignore proxy settings for. Optionally this may be set to * to bypass proxy settings for all hostnames domains or ip addresses.

Validations:

  • String
foreman_virt_who_configure_config[organization_id]
optional

Organization of the virt-who configuration

Validations:

  • Integer
foreman_virt_who_configure_config[prism_flavor]
optional , nil allowed

Select the Prism flavor you are connecting to

Validations:

  • Must be one of: central, element.
foreman_virt_who_configure_config[ahv_internal_debug]
optional , nil allowed

Option Enable debugging output is required to enable AHV internal debug. It provides extra AHV debug information when both options are enabled

Validations:

  • Must be one of: true, false, 1, 0.
>>>

DELETE /foreman_virt_who_configure/api/v2/configs/:id
Delete a virt-who configuration

Examples

DELETE /foreman_virt_who_configure/api/configs/51
{
  "config": {}
}
200
{
  "id": 51,
  "interval": 120,
  "hypervisor_id": "hostname",
  "listing_mode": 0,
  "whitelist": null,
  "blacklist": null,
  "compute_resource_id": null,
  "organization_id": 447626492,
  "service_user_id": 49,
  "created_at": "2024-05-23T19:44:56.587Z",
  "updated_at": "2024-05-23T19:44:56.650Z",
  "debug": false,
  "hypervisor_type": "esx",
  "hypervisor_server": "vmware.example.com",
  "hypervisor_username": "root",
  "hypervisor_password": "changeme",
  "satellite_url": "foreman.example.com",
  "no_proxy": null,
  "last_report_at": "2024-05-23T19:43:56.586Z",
  "out_of_date_at": "2024-05-23T21:43:56.586Z",
  "name": "config 42",
  "filter_host_parents": null,
  "exclude_host_parents": null,
  "kubeconfig_path": null,
  "http_proxy_id": null,
  "prism_flavor": null,
  "ahv_internal_debug": null
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
id
required

Configuration numeric identifier

Validations:

  • Must be a number.