Using the Satellite REST API

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

   Example request:

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

   Example response:

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

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}

3. Create a lifecycle environment by using the prior option set to 1.

   Example request:

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

   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

   In the command output, you can see the ID for this lifecycle environment is 2, and the lifecycle environment before this one is 1. Use the lifecycle 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}

5. Create a lifecycle environment, by using the prior option set to 2.

   Example request:

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

   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

   In the command output, you can see the ID for this lifecycle environment is 3, and the lifecycle environment before 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

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

   Example request:

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

3. Assign the file size to the variable size:

   Example request:

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

4. Create an upload request that returns the upload ID of the request by using size and checksum.

   Example request:

   $ curl -H 'Content-Type: application/json' -X POST -k \
   -u My_User_Name:My_Password \
   -d "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads

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

   Example request:

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

5. Assign the upload ID to the variable upload_id:

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

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

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 requests to Satellite unless stated otherwise. Combine the upload ID, MIME type, and other parameters to upload content.

   Example request:

   $ curl -u My_User_Name:My_Password -H Accept:application/json -H \
   Content-Type:multipart/form-data --request PUT --data-urlencode size=$size --data-urlencode offset=0 \
   --data-urlencode content@${path} \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

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

   Example request:

   $ curl -H "Content-Type:application/json" -X PUT -u \
   My_User_Name:My_Password -k -d \
   "{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \
   \"checksum\": \"$checksum\" }]}" \
   https://satellite.example.com/katello/api/v2/repositories/76/import_uploads

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 My_User_Name:My_Password -d "{}" \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

1. Assign the package name to the variable name:

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

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

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

3. Assign the file size to the variable size:

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

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

   Example request:

   $ curl -H 'Content-Type: application/json' -X POST -k \
   -u My_User_Name:My_Password -d "{\"size\": \"$size\", \
   \"checksum\":\"$checksum\"}" \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads

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

   Example output

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

5. Assign the upload ID to the variable upload_id:

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

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

   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

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

   $ export path=/root/tmp/bpftool

8. Upload the file chunks. The offset starts at 0 bytes for the first chunk and increases by 2000000 bytes 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 My_User_Name:My_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://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u My_User_Name:My_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://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u My_User_Name:My_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://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $curl -u My_User_Name:My_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://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id
   
   $ curl -u My_User_Name:My_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://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

9. Import the complete upload to the repository:

   $ curl -H "Content-Type:application/json" -X PUT -u \
   My_User_Name:My_Password -k -d \
   "{\"uploads\":[{\"id\": \"$upload_id\", \
   \"name\": \"$name\", \"checksum\": \"$checksum\" }]}" \
   https://satellite.example.com/katello/api/v2/repositories/76/import_uploads

10. Delete the upload request:

    $ curl -H 'Content-Type: application/json' -X DELETE -k \
    -u My_User_Name:My_Password -d "{}" \
    https://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

Procedure

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 --user My_User_Name:My_Password \
   https://satellite.example.com/api/v2/hosts?search=os_title=\"RedHat+7.7\",model=\"PowerEdge+R330\" \
   | python3 -m json.tool

   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
   }

Procedure

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

   • List all Smart Class Parameters.

     Example request:

     $ curl --request GET --user My_User_Name:My_Password \
     https://satellite.example.com/api/smart_class_parameters

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

     $ curl --request GET --user My_User_Name:My_Password \
     https://satellite.example.com/api/puppetclasses/5/smart_class_parameters

     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, use the --data option to pass URL encoded data.

     Example request:

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

     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 --user My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/63

3. Enable overriding of parameter values.

   Example request:

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

   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 Capsules.

4. Add custom override matchers.

   Example request:

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

   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 My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/63/override_values/3

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 My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters?search=puppetclass_name=motd \
   | python3 -m json.tool

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. 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": ""
   }

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 My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/3 \
   | python3 -m json.tool > output_file.json

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

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": ""
   }

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": ""
   }

7. Submit the file to Satellite:

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

Procedure

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

   Example request:

   $ curl --user My_User_Name:My_Password \
   https://satellite.example.com/api/v2/compliance/arf_reports/ | python3 -m json.tool

   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

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

   Example request:

   $ curl --user My_User_Name:My_Password \
   --header "Content-Type: application/json" \
   --request DELETE https://satellite.example.com/api/v2/compliance/arf_reports/405

   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