Chapter 5. Using the Red Hat Satellite API

1. Choose an existing life cycle environment that you want to use as a starting point. List the environment using its ID, in this case, the environment with ID 1:

   Example request:

   $ curl --request GET --user sat_username:sat_password --insecure \
   https://satellite.example.com/katello/api/environments/1 \
   | python3 -m json.tool

   Copy to Clipboard Toggle word wrap

   Example response:

   	output omitted
      "id": 1,
      "label": "Library",
   	output omitted
       "prior": null,
       "successor": null,
     output truncated

   Copy to Clipboard Toggle word wrap

2. Create a JSON file, for example, life-cycle.json, with the following content:

   {"organization_id":1,"label":"api-dev","name":"API Development","prior":1}

   Copy to Clipboard Toggle word wrap

3. Create a life cycle environment using the prior option set to 1.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request POST --user sat_username:sat_password --insecure \
   --data @life-cycle.json \
   https://satellite.example.com/katello/api/environments \
   | python3 -m json.tool

   Copy to Clipboard Toggle word wrap

   Example response:

         output omitted
       "description": null,
       "id": 2,
       "label": "api-dev",
       "library": false,
       "name": "API Development",
       "organization": {
           "id": 1,
           "label": "Default_Organization",
           "name": "Default Organization"
       },
       "permissions": {
           "destroy_lifecycle_environments": true,
           "edit_lifecycle_environments": true,
           "promote_or_remove_content_views_to_environments": true,
           "view_lifecycle_environments": true
       },
      "prior": {
           "id": 1,
           "name": "Library"
       },
       output truncated

   Copy to Clipboard Toggle word wrap

   In the command output, you can see the ID for this life cycle environment is 2, and the life cycle environment prior to this one is 1. Use the life cycle environment with ID 2 to create a successor to this environment.

4. Edit the previously created life-cycle.json file, updating the label, name, and prior values.

   {"organization_id":1,"label":"api-qa","name":"API QA","prior":2}

   Copy to Clipboard Toggle word wrap

5. Create a life cycle environment, using the prior option set to 2.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request POST --user sat_username:sat_password --insecure \
   --data @life-cycle.json \
   https://satellite.example.com/katello/api/environments \
   | python3 -m json.tool

   Copy to Clipboard Toggle word wrap

   Example response:

         output omitted
      "description": null,
      "id": 3,
       "label": "api-qa",
       "library": false,
       "name": "API QA",
       "organization": {
           "id": 1,
           "label": "Default_Organization",
           "name": "Default Organization"
       },
       "permissions": {
           "destroy_lifecycle_environments": true,
           "edit_lifecycle_environments": true,
           "promote_or_remove_content_views_to_environments": true,
           "view_lifecycle_environments": true
       },
      "prior": {
           "id": 2,
           "name": "API Development"
       },
       "successor": null,
       output truncated

   Copy to Clipboard Toggle word wrap

   In the command output, you can see the ID for this life cycle environment is 3, and the life cycle environment prior to this one is 2.

1. Create an upload request.
2. Upload the content.
3. Import the content.
4. Delete the upload request.

Procedure

1. Assign the package name to the variable name:

   Example request:

   $ export name=jq-1.6-2.el7.x86_64.rpm

   Copy to Clipboard Toggle word wrap

2. Assign the checksum of the file to the variable checksum:

   Example request:

   $ export checksum=$(sha256sum $name|cut -c 1-65)

   Copy to Clipboard Toggle word wrap

3. Assign the file size to the variable size:

   Example request:

   $ export size=$(du -bs $name|cut -f 1)

   Copy to Clipboard Toggle word wrap

4. The following command creates a new upload request and returns the upload ID of the request using size and checksum.

   Example request:

   $ curl -H 'Content-Type: application/json' -X POST -k \
   -u sat_username:sat_password -d "{\"size\": \"$size\", \
   \"checksum\":\"$checksum\"}" \
   https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads

   Copy to Clipboard Toggle word wrap

   where 76, in this case, is an example Repository ID.

   Example request:

   {"upload_id":"37eb5900-597e-4ac3-9bc5-2250c302fdc4"}

   Copy to Clipboard Toggle word wrap

5. Assign the upload ID to the variable upload_id:

   Example request:

   $ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4

   Copy to Clipboard Toggle word wrap

6. Assign the path of the package you want to upload to the variable path:

   $ export path=/root/jq/jq-1.6-2.el7.x86_64.rpm

   Copy to Clipboard Toggle word wrap

7. Upload your content. Ensure you use the correct MIME type when you upload data. The API uses the application/json MIME type for the majority of requests to Satellite 6. Combine the upload_id, MIME type, and other parameters to upload content.

   Example request:

   $ curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data -X PUT --data-urlencode size=$size --data-urlencode offset=0 \
   --data-urlencode content@${path} \
   https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id

   Copy to Clipboard Toggle word wrap

8. After you have uploaded the content to the Satellite Server, you need to import it into the appropriate repository. Until you complete this step, the Satellite Server does not detect the new content.

   Example request:

   $ curl -H "Content-Type:application/json" -X PUT -u \
   sat_username:sat_password -k -d \
   "{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \
   \"checksum\": \"$checksum\" }]}" \
   https://$(hostname -f)/katello/api/v2/repositories/76/import_uploads

   Copy to Clipboard Toggle word wrap

9. After you have successfully uploaded and imported your content, you can delete the upload request. This frees any temporary disk space that data is using during the upload.

   Example request:

   $ curl -H 'Content-Type: application/json' -X DELETE -k \
   -u sat_username:sat_password -d "{}" \
   https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id

   Copy to Clipboard Toggle word wrap

1. Assign the package name to the variable name:

   $ export name=bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm

   Copy to Clipboard Toggle word wrap

2. Assign the checksum of the file to the variable checksum:

   $ export  checksum=$(sha256sum $name|cut -c 1-65)

   Copy to Clipboard Toggle word wrap

3. Assign the file size to the variable size:

   $ export  size=$(du -bs $name|cut -f 1)

   Copy to Clipboard Toggle word wrap

4. The following command creates a new upload request and returns the upload ID of the request using size and checksum.

   Example request:

   $ curl -H 'Content-Type: application/json' -X POST -k \
   -u sat_username:sat_password -d "{\"size\": \"$size\", \
   \"checksum\":\"$checksum\"}" \
   https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads

   Copy to Clipboard Toggle word wrap

   where 76, in this case, is an example Repository ID.

   Example output

   {"upload_id":"37eb5900-597e-4ac3-9bc5-2250c302fdc4"}

   Copy to Clipboard Toggle word wrap

5. Assign the upload ID to the variable upload_id:

   $ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4

   Copy to Clipboard Toggle word wrap

6. Split the file in 2MB chunks:

   $ split --bytes 2MB --numeric-suffixes \
   --suffix-length=1 bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm bpftool

   Copy to Clipboard Toggle word wrap

   Example output

   $ ls bpftool[0-9] -l
   -rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool0
   -rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool1
   -rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool2
   -rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool3
   -rw-r--r--. 1 root root  868648 Mar 31 14:15 bpftool4

   Copy to Clipboard Toggle word wrap

7. Assign the prefix of the split files to the variable path.

   $ export path=/root/tmp/bpftool

   Copy to Clipboard Toggle word wrap

8. Upload the file chunks. The offset starts at 0 for the first chunk and increases by 2000000 for each file. Note the use of the offset parameter and how it relates to the file size. Note also that the indexes are used after the path variable, for example, ${path}0, ${path}1.

   Example requests:

   $ curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data  \
   -X PUT --data-urlencode size=$size --data-urlencode offset=0 \
   --data-urlencode content@${path}0 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data \
   -X PUT --data-urlencode size=$size --data-urlencode offset=2000000 \
   --data-urlencode content@${path}1 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data \
   -X PUT --data-urlencode size=$size --data-urlencode offset=4000000 \
   --data-urlencode content@${path}2 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data \
   -X PUT --data-urlencode size=$size --data-urlencode offset=6000000
   --data-urlencode content@${path}3 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u sat_username:sat_password -H Accept:application/json -H \
   Content-Type:multipart/form-data \
   -X PUT --data-urlencode size=$size --data-urlencode offset=8000000 \
   --data-urlencode content@${path}4 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id

   Copy to Clipboard Toggle word wrap

9. Import the complete upload to the repository:

   $ curl -H "Content-Type:application/json" -X PUT -u \
   sat_username:sat_password -k -d \
   "{\"uploads\":[{\"id\": \"$upload_id\", \
   \"name\": \"$name\", \"checksum\": \"$checksum\" }]}" \
   https://$(hostname -f)/katello/api/v2/repositories/76/import_uploads

   Copy to Clipboard Toggle word wrap

10. Delete the upload request:

    $ curl -H 'Content-Type: application/json' -X DELETE -k \
    -u sat_username:sat_password -d "{}" \
    https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id

    Copy to Clipboard Toggle word wrap

1. In the Satellite web UI, navigate to Hosts > All Hosts and click the Search field to display a list of search parameters.
2. Locate the search parameters that you want to use. For this example, locate os_title and model.

3. Combine the search parameters in your API query as follows:

   Example request:

   $ curl --insecure --user sat_username:sat_password \
   https://satellite.example.com/api/v2/hosts?search=os_title=\"RedHat+7.7\",model=\"PowerEdge+R330\" \
   | python3 -m json.tool

   Copy to Clipboard Toggle word wrap
   Note

   The example request uses python3 to format the respone from the Satellite Server. On RHEL 7 and some older systems, you must use python instead of python3.

   Example response:

     {
       ...
       "results": [
           {
               "model_id": 1,
               "model_name": "PowerEdge R330",
               "name": "satellite.example.com",
               "operatingsystem_id": 1,
               "operatingsystem_name": "RedHat 7.7",
               ...
           }
       ],
       "search": "os_title=\"RedHat 7.7\",model=\"PowerEdge R330\"",
       "subtotal": 1,
       "total": 11
   }

   Copy to Clipboard Toggle word wrap

1. Find the ID of the Smart Class parameter you want to change:

   • List all Smart Class Parameters.

     Example request:

     $ curl --request GET --insecure --user sat_username:sat_password \
     https://satellite.example.com/api/smart_class_parameters

     Copy to Clipboard Toggle word wrap

   • If you know the Puppet class ID, for example 5, you can restrict the scope:

     Example request:

     $ curl --request GET --insecure --user sat_username:sat_password \
     https://satellite.example.com/api/puppetclasses/5/smart_class_parameters

     Copy to Clipboard Toggle word wrap

     Both calls accept a search parameter. You can view the full list of searchable fields in the Satellite web UI. Navigate to Configure > Smart variables and click in the search query box to reveal the list of fields.

     Two particularly useful search parameters are puppetclass_name and key, which you can use to search for a specific parameter. For example, using the --data option to pass URL encoded data.

     Example request:

     $ curl --request GET --insecure --user sat_username:sat_password \
     --data 'search=puppetclass_name = access_insights_client and key = authmethod' \
     https://satellite.example.com/api/smart_class_parameters

     Copy to Clipboard Toggle word wrap

     Satellite supports standard scoped-search syntax.

2. When you find the ID of the parameter, list the full details including current override values.

   Example request:

   $ curl --request GET --insecure --user sat_username:sat_password \
   https://satellite.example.com/api/smart_class_parameters/63

   Copy to Clipboard Toggle word wrap

3. Enable overriding of parameter values.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT --insecure --user sat_username:sat_password \
   --data '{"smart_class_parameter":{"override":true}}' \
   https://satellite.example.com/api/smart_class_parameters/63

   Copy to Clipboard Toggle word wrap

   Note that you cannot create or delete the parameters manually. You can only modify their attributes. Satellite creates and deletes parameters only upon class import from a proxy.

4. Add custom override matchers.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT --insecure --user sat_username:sat_password \
   --data '{"smart_class_parameter":{"override_value":{"match":"hostgroup=Test","value":"2.4.6"}}}' \
   https://satellite.example.com/api/smart_class_parameters/63

   Copy to Clipboard Toggle word wrap

   For more information about override values, see https://satellite.example.com/apidoc/v2/override_values.html.

5. You can delete override values.

   Example request:

   $ curl --request DELETE --user sat_username:sat_password \
   https://satellite.example.com/api/smart_class_parameters/63/override_values/3

   Copy to Clipboard Toggle word wrap

1. Search for the Puppet Class by name, motd in this case.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request GET --user sat_user:sat_password --insecure \
   https://satellite.example.com/api/smart_class_parameters?search=puppetclass_name=motd \
   | python3 -m json.tool

   Copy to Clipboard Toggle word wrap

2. Examine the following output. Each Smart Class Parameter has an ID that is global for the same Satellite instance. The content parameter of the motd class has id=3 in this Satellite Server. Do not confuse this with the Puppet Class ID that displays before the Puppet Class name.

   Example response:

   {
   	"avoid_duplicates": false,
   		"created_at": "2017-02-06 12:37:48 UTC", # Remove this line.
   			"default_value": "", # Add a new value here.
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": false, # Set the override value to true.
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values": [], # Remove this line.
   			"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"updated_at": "2017-02-07 11:56:55 UTC", # Remove this line.
   			"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

   Copy to Clipboard Toggle word wrap

3. Use the parameter ID 3 to get the information specific to the motd parameter and redirect the output to a file, for example, output_file.json.

   Example request:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" --request GET \
   --user sat_user:sat_password --insecure \`
   https://satellite.example.com/api/smart_class_parameters/3 \
   | python3 -m json.tool > output_file.json

   Copy to Clipboard Toggle word wrap

4. Copy the file created in the previous step to a new file for editing, for example, changed_file.json:

   $ cp output_file.json changed_file.json

   Copy to Clipboard Toggle word wrap

5. Modify the required values in the file. In this example, change the content parameter of the motd module, which requires changing the override option from false to true:

   {
   	"avoid_duplicates": false,
   		"created_at": "2017-02-06 12:37:48 UTC", # Remove this line.
   			"default_value": "", # Add a new value here.
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": false, # Set the override value to true.
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values": [], # Remove this line.
   			"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"updated_at": "2017-02-07 11:56:55 UTC", # Remove this line.
   			"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

   Copy to Clipboard Toggle word wrap

6. After editing the file, verify that it looks as follows and then save the changes:

   {
   	"avoid_duplicates": false,
   		"default_value": "No Unauthorized Access Allowed",
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": true,
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

   Copy to Clipboard Toggle word wrap

7. Apply the changes to Satellite Server:

   $ curl --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT --user sat_username:sat_password --insecure \
   --data @changed_file.json \
   https://satellite.example.com/api/smart_class_parameters/3

   Copy to Clipboard Toggle word wrap

1. List all OpenSCAP reports. Note the IDs of the reports that you want to delete.

   Example request:

   curl --insecure --user username:_password_ \
   https://satellite.example.com/api/v2/compliance/arf_reports/ | python3 -m json.tool

   Copy to Clipboard Toggle word wrap

   Example response:

     % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                    Dload  Upload   Total   Spent    Left  Speed
   100  3252    0  3252    0     0   4319      0 --:--:-- --:--:-- --:--:--  4318
   {
       "page": 1,
       "per_page": 20,
       "results": [
           {
               "created_at": "2017-05-16 13:27:09 UTC",
               "failed": 0,
               "host": "host1.example.com",
               "id": 404,
               "othered": 0,
               "passed": 0,
               "updated_at": "2017-05-16 13:27:09 UTC"
           },
           {
               "created_at": "2017-05-16 13:26:07 UTC",
               "failed": 0,
               "host": "host2.example.com,
               "id": 405,
               "othered": 0,
               "passed": 0,
               "updated_at": "2017-05-16 13:26:07 UTC"
           },
           {
               "created_at": "2017-05-16 13:25:07 UTC",
               "failed": 0,
               "host": "host3.example.com",
               "id": 406,
               "othered": 0,
               "passed": 0,
               "updated_at": "2017-05-16 13:25:07 UTC"
           },
           {
               "created_at": "2017-05-16 13:24:07 UTC",
               "failed": 0,
               "host": "host4.example.com",
               "id": 407,
               "othered": 0,
               "passed": 0,
               "updated_at": "2017-05-16 13:24:07 UTC"
           },
       ],
       "search": null,
       "sort": {
           "by": null,
           "order": null
       },
       "subtotal": 29,
       "total": 29

   Copy to Clipboard Toggle word wrap

2. Using an ID from the previous step, delete the OpenSCAP report. Repeat for each ID that you want to delete.

   Example request:

   # curl --insecure --user username:_password_ \
   --header "Content-Type: application/json" \
   --request DELETE https://satellite.example.com/api/v2/compliance/arf_reports/405

   Copy to Clipboard Toggle word wrap

   Example response:

   HTTP/1.1 200 OK
   Date: Thu, 18 May 2017 07:14:36 GMT
   Server: Apache/2.4.6 (Red Hat Enterprise Linux)
   X-Frame-Options: SAMEORIGIN
   X-XSS-Protection: 1; mode=block
   X-Content-Type-Options: nosniff
   Foreman_version: 1.11.0.76
   Foreman_api_version: 2
   Apipie-Checksum: 2d39dc59aed19120d2359f7515e10d76
   Cache-Control: max-age=0, private, must-revalidate
   X-Request-Id: f47eb877-35c7-41fe-b866-34274b56c506
   X-Runtime: 0.661831
   X-Powered-By: Phusion Passenger 4.0.18
   Set-Cookie: request_method=DELETE; path=/
   Set-Cookie: _session_id=d58fe2649e6788b87f46eabf8a461edd; path=/; secure; HttpOnly
   ETag: "2574955fc0afc47cb5394ce95553f428"
   Status: 200 OK
   Vary: Accept-Encoding
   Transfer-Encoding: chunked
   Content-Type: application/json; charset=utf-8

   Copy to Clipboard Toggle word wrap