1. Introduction to Foreman API

With the Representational State Transfer (REST) API of Foreman, you can control your Foreman environment outside of the standard web interface. That way, you can integrate your Foreman with custom scripts or external applications over HTTP.

1.1. Overview of the Foreman API

Integrate with enterprise systems, automate repetitive tasks, and manage your infrastructure programmatically using the resource-based REST model of the Foreman API. You can use any HTTP client to interact with Foreman.

The benefits of using the REST API are:

  • Broad client support – any programming language, framework, or system with support for HTTP protocol can use the API.

  • Self-descriptive – client applications require minimal knowledge of the Foreman infrastructure because a user discovers many details at runtime.

  • Resource-based model – the resource-based REST model provides a natural way to manage a virtualization platform.

You can use the REST API to perform the following tasks:

  • Integrate with enterprise IT systems.

  • Integrate with third-party applications.

  • Perform automated maintenance or error checking tasks.

  • Automate repetitive tasks with scripts.

1.2. Foreman API compared to Hammer CLI

Hammer serves as a human-friendly interface to Foreman API. Use Hammer for interactive tasks and testing API calls, but use the API directly for better performance when executing many commands in scripts.

For example, to test responses to API calls before applying them in a script, use the --debug option to inspect API calls that Hammer issues: hammer --debug organization list.

In the background, each Hammer command first establishes a binding to the API, then sends a request. This can have performance implications when executing a large number of Hammer commands in sequence. In contrast, a script communicating directly with the API establishes the binding only once.

Additional resources

1.3. Getting help with Foreman API

You can use the API reference on your Foreman server to view information about API endpoints supported for Foreman API integrations.

View the full API reference on your Foreman server at the following URL:

https://foreman.example.com/apidoc/

Replace foreman.example.com with the FQDN of your Foreman server.

2. API syntax

Understanding the basic syntax of API requests and JSON responses enables you to construct valid API calls and interpret the returned data.

Important

Even though versions 1 and 2 of the Foreman API are available, Foreman community only supports version 2.

2.1. API request composition

You can use the built-in API reference documentation to compose valid API requests.

This example shows how to compose a curl API request.

The built-in API reference shows the API route, or path, preceded by an HTTP method:

HTTP_METHOD API_ROUTE

To work with the API, construct a command by using the curl command syntax and the API route from the reference document:

$ curl \
--data @My_Input_File.json \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--output My_Output_File
--request HTTP_METHOD \
--user "My_User_Name:My_Password" \
API_ROUTE \
| python3 -m json.tool
--data

For POST and PUT requests, use the --data option to pass JSON-formatted data.

--header

When passing the JSON data with the --data option, you must specify the following headers with the --header option.

--output

When downloading content from Foreman server, specify the output file with the --output option.

--request

To use curl for the API call, specify an HTTP method with the --request option. For example, --request POST.

--user

Provide Foreman user credentials with the --user option.

API_ROUTE

Use the API route in the following format: \https://foreman.example.com/api/architectures. In Foreman, version 2 of the API is the default. Therefore, it is not necessary to use v2 in the URL for API calls.

json.tool

Redirect the output to the Python json.tool module to make the output easier to read.

Additional resources

2.1.1. Using the GET HTTP method

Use the GET HTTP method to get data from the API about an existing entry or resource. This example requests the number of registered hosts.

Procedure

  • Submit a GET request by using curl.

    Example API request:

    $ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/hosts \
| python3 -m json.tool

    Example API response:

    {
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
    output truncated
}

    The response from the API indicates that there are two results in total, this is the first page of the results, and the maximum results per page is set to 20. For more information, see JSON response format.

2.2. JSON response format

Foreman API returns results in JSON format, which you can parse programmatically to extract data from single-object responses or collections responses.

2.2.1. JSON response format for single objects

You can use single-object JSON responses to work with a single object. API requests to a single object require the unique identifier :id of the object.

This is an example of the format for a single-object request for the Foreman domain which ID is 23:

API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/domains/23 \
| python3 -m json.tool
API response
{
    "id": 23,
    "name": "qa.lab.example.com",
    "fullname": "QA",
    "dns_id": 10,
    "created_at": "2024-08-13T09:02:31Z",
    "updated_at": "2024-08-13T09:02:31Z"
}

2.2.2. JSON response format for collections

Collections return lists of objects, such as hosts and domains. Each response includes pagination metadata and a results section containing the data you can iterate through.

This is an example of the format for a collection request for a list of Foreman domains:

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/domains \
| python3 -m json.tool
Example API response
{
    "total": 3,
    "subtotal": 3,
    "page": 1,
    "per_page": 20,
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "results": [
        {
            "id": 23,
            "name": "qa.lab.example.com",
            "fullname": "QA",
            "dns_id": 10,
            "created_at": "2024-08-13T09:02:31Z",
            "updated_at": "2024-08-13T09:02:31Z"
        },
        {
            "id": 25,
            "name": "dev.lab.example.com",
            "fullname": "DEVEL",
            "dns_id": 8,
            "created_at": "2024-08-13T08:32:48Z",
            "updated_at": "2024-08-14T07:04:03Z"
        },
        {
            "id": 32,
            "name": "hr.lab.example.com",
            "fullname": "HR",
            "dns_id": 8,
            "created_at": "2024-08-16T08:32:48Z",
            "updated_at": "2024-08-16T07:04:03Z"
        }
    ]
}

2.2.3. JSON response metadata

Review the metadata fields in Foreman API responses to understand pagination, search results, and collection information when working with the API.

Foreman API responses contain the following metadata fields:

total

The total number of objects without any search parameters.

subtotal

The number of objects returned with the given search parameters. If there is no search, then subtotal is equal to total.

page

The page number.

per_page

The maximum number of objects returned per page.

limit

The specified number of objects to return in a collection response.

offset

The number of objects skipped before returning a collection.

search

The search string based on scoped_scoped syntax.

sort

  • by – Specifies by what field the API sorts the collection.

  • order – The sort order, either ASC for ascending or DESC for descending.

results

The collection of objects.

2.3. Relating API error messages to the API reference

You can map API error messages to the corresponding sections in the API reference documentation by translating the RAILS error format to the reference format. This helps you locate the relevant documentation when troubleshooting API errors.

The API uses a RAILs format to indicate an error:

Nested_Resource.Attribute_Name

This translates to the following format used in the API reference:

Resource[Nested_Resource_attributes][Attribute_Name_id]

3. API call authentication

You must authenticate API calls to Foreman server by using SSL certificates and valid user credentials, with options for HTTP basic authentication, SSL client certificates, or personal access tokens.

3.1. SSL authentication overview

Foreman requires HTTPS for all API communications to provide encryption and identity verification. You can use either self-signed certificates or custom SSL certificates you configure.

Foreman nightly does not support non-SSL communications.

By default, Foreman server uses a self-signed certificate. This certificate acts as both the server certificate to verify the encryption key and the certificate authority (CA) to trust the identity of Foreman server.

Additional resources

3.2. HTTP authentication overview

You must provide valid Foreman credentials to access the Foreman API.

The API uses HTTP Basic authentication to send encoded user credentials in the Authorization header. If a request does not include an appropriate Authorization header, the API returns a 401 Authorization Required error.

Important

Basic authentication involves potentially sensitive information, for example, it sends passwords as plain text. The REST API requires HTTPS for transport-level encryption of plain text requests.

Some base64 libraries break encoded credentials into multiple lines and terminate each line with a newline character. This invalidates the header and causes a faulty request. The Authorization header requires the encoded credentials to be on a single line within the header.

Additional resources

3.3. Token authentication overview

You can use Personal Access Tokens to authenticate API requests instead of passwords. Additionally, you can manage your security by setting expiration dates or revoking tokens at any time.

3.3.1. Creating a Personal Access Token

Create a Personal Access Token to authenticate API requests without sharing your password.

Prerequisites

  • Your user account has a role that grants the create_personal_access_tokens permission.

Procedure

  1. In the Foreman web UI, navigate to Administer > Users.

  2. Select a user for which you want to create a Personal Access Token.

  3. On the Personal Access Tokens tab, click Add Personal Access Token.

  4. Enter a Name for you Personal Access Token.

  5. Optional: Select the Expires date to set an expiration date. If you do not set an expiration date, your Personal Access Token will never expire unless revoked.

  6. Click Submit. You now have the Personal Access Token available to you on the Personal Access Tokens tab.

    Important

    Ensure to store your Personal Access Token as you will not be able to access it again after you leave the page or create a new Personal Access Token. You can click Copy to clipboard to copy your Personal Access Token.
Verification

  1. Make an API request to your Foreman server and authenticate with your Personal Access Token:

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://foreman.example.com/api/status

  2. You should receive a response with status 200, for example:

    {"foreman_version":"nightly.0","result":"ok","status":200,"version":"3.5.1.10","api_version":2}

    If you go back to Personal Access Tokens tab, you can see the updated Last Used time next to your Personal Access Token.

3.3.2. Revoking a Personal Access Token

Revoke a Personal Access Token before its expiration date when a token is compromised or no longer needed for API access.

Procedure

  1. In the Foreman web UI, navigate to Administer > Users.

  2. Select a user for which you want to revoke the Personal Access Token.

  3. On the Personal Access Tokens tab, locate the Personal Access Token you want to revoke.

  4. Click Revoke in the Actions column next to the Personal Access Token you want to revoke.

Verification

  1. Make an API request to your Foreman server and try to authenticate with the revoked Personal Access Token:

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://foreman.example.com/api/status

  2. You receive the following error message:

    {
  "error": {"message":"Unable to authenticate user My_Username"}
}

4. API requests in various languages

You can interact with Foreman API using curl for quick testing, Ruby for automation scripts with apipie bindings, or Python for integration with existing Python-based workflows.

4.1. Calling the API in curl

You can use curl to test API endpoints, debug requests, and perform quick operations without writing scripts.

You can use curl to manipulate resources on your Foreman server. API calls to Foreman require data in json format.

Foreman requires the use of HTTPS, and by default, a certificate for host identification.

For user authentication, you can use the --user option to provide Foreman user credentials in the form --user My_User_Name:My_Password. If you do not include the password, the command prompts you to enter it. To reduce security risks, do not include the password as part of the command, because it then becomes part of your shell history. For simplicity, the examples in this section include the password.

Be aware that if you use the --silent option, curl does not display a progress meter or any error messages.

Examples in this chapter use the Python json.tool module to format the output.

Additional resources

4.1.1. Passing JSON data to the API request

You can pass JSON-formatted data to Foreman API requests either as inline strings or external files.

When specifying JSON data with the --data option, you must set the following HTTP headers with the --header option:

--header "Accept: application/json" \
--header "Content-Type: application/json"

Use one of the following options to include data with the --data option.

JSON-formatted string

Enclose the quoted JSON-formatted data in curly braces {}. When passing a value for a JSON type parameter, you must escape quotation marks " with backslashes \. For example, within curly braces, you must format "Example JSON Variable" as \"Example JSON Variable\":

--data {"id":44, "smart_class_parameter":{"override":"true", "parameter_type":"json", "default_value":"{\"GRUB_CMDLINE_LINUX\": {\"audit\":\"1\",\"crashkernel\":\"true\"}}"}}
JSON-formatted file

The unquoted JSON-formatted data enclosed in a file and specified by the @ sign and the filename. For example:

--data @file.json

Using external files for JSON formatted data has the following advantages:

  • You can use your favorite text editor.

  • You can use syntax checker to find and avoid mistakes.

  • You can use tools to check the validity of JSON data or to reformat it.

Use the json_verify tool to check the validity of the JSON file:

$ json_verify < file.json

4.1.2. Retrieving a list of resources

You can retrieve lists of Foreman resources such as users, hosts, or organizations using GET requests, with responses containing both metadata for pagination and the actual resource data.

This example is a basic request that returns a list of Foreman resources, Foreman users in this case. Such requests return a list of data wrapped in metadata, while other request types only return the actual object.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/users \
| python3 -m json.tool
Example API response
{
    "page": 1,
    "per_page": 20,
    "results": [
        {
            "admin": false,
            "auth_source_id": 1,
            "auth_source_name": "Internal",
            "created_at": "2024-09-21 08:59:22 UTC",
            "default_location": null,
            "default_organization": null,
            "description": "",
            "effective_admin": false,
            "firstname": "",
            "id": 5,
            "last_login_on": "2024-09-21 09:03:25 UTC",
            "lastname": "",
            "locale": null,
            "locations": [],
            "login": "test",
            "mail": "test@example.com",
            "organizations": [
                {
                    "id": 1,
                    "name": "Default Organization"
                }
            ],
            "ssh_keys": [],
            "timezone": null,
            "updated_at": "2024-09-21 09:04:45 UTC"
        },
        {
            "admin": true,
            "auth_source_id": 1,
            "auth_source_name": "Internal",
            "created_at": "2024-09-20 07:09:41 UTC",
            "default_location": null,
            "default_organization": {
                "description": null,
                "id": 1,
                "name": "Default Organization",
                "title": "Default Organization"
            },
            "description": "",
            "effective_admin": true,
            "firstname": "Admin",
            "id": 4,
            "last_login_on": "2024-12-07 07:31:09 UTC",
            "lastname": "User",
            "locale": null,
            "locations": [
                {
                    "id": 2,
                    "name": "Default Location"
                }
            ],
            "login": "admin",
            "mail": "admin@example.com",
            "organizations": [
                {
                    "id": 1,
                    "name": "Default Organization"
                }
            ],
            "ssh_keys": [],
            "timezone": null,
            "updated_at": "2024-11-14 08:19:46 UTC"
        }
    ],
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "subtotal": 2,
    "total": 2
}

4.1.3. Creating a user

You can create Foreman user accounts using POST requests.

This example adds a user account named test_user.

Example API request
$ curl \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--request POST \
--user My_User_Name:My_Password \
--data "{\"firstname\":\"Test Name\",\"mail\":\"test@example.com\",\"login\":\"test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \
https://foreman.example.com/api/users \
| python3 -m json.tool

4.1.4. Modifying a user

You can modify Foreman user accounts using PUT requests by specifying the user ID and the fields you want to update, such as login name or email address.

This example changes the given name and login for the test_user account.

Example API request
$ curl \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--request PUT \
--user My_User_Name:My_Password \
--data "{\"firstname\":\"New Test Name\",\"mail\":\"test@example.com\",\"login\":\"new_test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \
https://foreman.example.com/api/users/8 \
| python3 -m json.tool

4.2. Calling the API in Ruby

You can use Ruby to automate complex Foreman workflows. Use REST client libraries or apipie bindings to get type-safe API calls with built-in validation.

Important

These are example scripts and commands. Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment.

4.3. Calling the API in Python

You can use Python with the requests module to integrate Foreman API calls into existing Python automation workflows, data processing pipelines, or DevOps tooling.

Important

These are example scripts and commands. Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment.

Example scripts in this section do not use SSL verification for interacting with the REST API.

5. API cheat sheet

Use the Foreman API to automate host management and searches.

You can use the API on Foreman server via HTTPS on port 443.

For example, in Ruby, you can specify the Foreman server URL as follows:

url = 'https://foreman.example.com/api/v2/'

You can use these values to fully automate your scripts, removing any need to verify which ports to use.

The following examples use curl for sending API requests.

5.1. Working with hosts

You can use API requests to manage hosts. Namely, you can list, query, search, and delete hosts programmatically.

5.1.1. Listing hosts

You can retrieve a list of all registered hosts from Foreman.

This example returns a list of registered hosts.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts \
| python3 -m json.tool
API response
{
      ...
       "total" => 2,
    "subtotal" => 2,
        "page" => 1,
    "per_page" => 1000,
      "search" => nil,
        "sort" => {
           "by" => nil,
        "order" => nil
    },
     "results" => [
      ...
}

5.1.2. Requesting information for a host

You can retrieve detailed information about a specific host, including architecture, build status, and capabilities.

This request returns information for host.example.com.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts/host.example.com \
| python3 -m json.tool
Example API response
{
    "all_puppetclasses": [],
    "architecture_id": 1,
    "architecture_name": "x86_64",
    "build": false,
    "capabilities": [
        "build"
    ],
    "certname": "host.example.com",
    "comment": null,
    "compute_profile_id": null,
    ...
}

5.1.3. Listing host facts

You can retrieve system facts such as hardware details, BIOS version, and installed software for a specific host.

This request returns all facts for the host foreman.example.com.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts/foreman.example.com/facts \
| python3 -m json.tool
Example API response
{
    ...
    "results": {
        "foreman.example.com": {
            "augeasversion": "1.0.0",
            "bios_release_date": "01/01/2007",
            "bios_version": "0.5.1",
            "blockdevice_sr0_size": "1073741312",
            "facterversion": "1.7.6",
            ...
}

5.1.4. Searching for hosts with matching patterns

You can filter hosts by hostname patterns or other matching criteria.

This query returns all hosts that match the pattern "example".

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts?search=example \
| python3 -m json.tool
Example API response
{
    ...
    "results": [
        {
            "name": "foreman.example.com",
            ...
        }
    ],
    "search": "example",
    ...
}

5.1.5. Searching for hosts in an environment

You can filter hosts by environment to retrieve all hosts assigned to a specific environment.

This query returns all hosts in the production environment.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts?search=environment=production \
| python3 -m json.tool
Example API response
{
    ...
    "results": [
        {
            "environment_name": "production",
            "name": "foreman.example.com",
            ...
        }
    ],
    "search": "environment=production",
    ...
}

5.1.6. Searching for hosts with a specific fact value

You can filter hosts by specific fact values such as host group, operating system, or custom facts.

This query returns all hosts with the host group My Host Group.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts?search=hostgroup=%22My+Host+Group%22 \
| python3 -m json.tool
Example API response
{
    ...
    "results": [
        {
            ...
            "hostgroup_id": 1,
            "hostgroup_name": "My Host Group",
            "name": "my-host.example.com",
            ...
        }
    ],
    "search": "hostgroup=\"My Host Group\"",
    ...
}

5.1.7. Deleting a host

You can permanently remove a host from Foreman when decommissioning a server, reclaiming software subscriptions, or clearing out stale inventory data to maintain accurate compliance reporting.

This example request deletes a host with a name host1.example.com.

Example API request
$ curl \
--request DELETE \
--user My_User_Name:My_Password \
https://foreman.example.com/api/v2/hosts/host1.example.com \
| python3 -m json.tool

5.1.8. Downloading a full-host boot disk image

You can download a bootable ISO image for a host to handle provisioning or recovery scenarios.

This request downloads a full boot disk image for a host by its ID.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
--output My_Image.iso \
https://foreman.example.com/api/bootdisk/hosts/host_ID?full=true

5.2. Using extended searches

You can combine search parameters in your API queries to filter hosts. This way you can target specific hosts by their operating system or hardware model.

For more information, see Working efficiently with Foreman web UI in Administering Foreman.

For example, you can search for hosts.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Click the Search field to display a list of search parameters.

  3. Locate the search parameters that you want to use. For this example, locate os_title and model.

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

    Example request:

    $ curl \
--user My_User_Name:My_Password \
https://foreman.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": "foreman.example.com",
            "operatingsystem_id": 1,
            "operatingsystem_name": "RedHat 7.7",
            ...
        }
    ],
    "search": "os_title=\"RedHat 7.7\",model=\"PowerEdge R330\"",
    "subtotal": 1,
    "total": 11
}

5.3. Using searches with pagination control

You can control how many results an API query returns per page and which page to retrieve in order to manage large datasets efficiently.

The per_page parameter specifies the number of results per page and the page parameter specifies which page, as calculated by the per_page parameter, to return.

The number of items to be presented is set using the setting entries_per_page, which defaults to 20. However, you can change it per request by using the parameter per_page.

This example returns a list of architectures for an organization with ID 1 in pages. The list contains 5 entries per page and returns the second page.

Example API request
$ curl \
--request GET \
--user My_User_Name:My_Password \
https://foreman.example.com/katello/api/architectures?organization_id=1&amp;per_page=5&amp;page=2

5.4. Overriding Smart Class parameters

You can override Smart Class parameters to customize Puppet configuration values for specific hosts or host groups. This way you customize different environments without changing the original Puppet classes.

You can find the full list of attributes that you can modify in the built-in API reference at https://foreman.example.com/apidoc/v2/smart_class_parameters/update.html.

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://foreman.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://foreman.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 Foreman 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://foreman.example.com/api/smart_class_parameters

      Foreman 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://foreman.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://foreman.example.com/api/smart_class_parameters/63

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

  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://foreman.example.com/api/smart_class_parameters/63

    For more information about override values, see https://foreman.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://foreman.example.com/api/smart_class_parameters/63/override_values/3

5.5. Modifying a Smart Class parameter by using an external file

You can modify Puppet Smart Class parameters by using external JSON files to simplify working with complex parameter values. That way, you can enable syntax highlighting and error detection in your editor.

This example uses a MOTD Puppet manifest.

Procedure

  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://foreman.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 Foreman 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": "2024-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": "2024-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://foreman.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": "2024-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": "2024-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 Foreman:

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

5.6. Deleting OpenSCAP reports

Delete OpenSCAP compliance reports to free up storage space or remove outdated scan results, either individually by ID or in bulk using a bash script for large-scale cleanup.

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://foreman.example.com/api/v2/compliance/arf_reports/ \
| python3 -m json.tool

    Example response:

    {
    "page": 1,
    "per_page": 20,
    "results": [
        {
            "created_at": "2024-05-16 13:27:09 UTC",
            "failed": 0,
            "host": "host1.example.com",
            "id": 404,
            "othered": 0,
            "passed": 0,
            "updated_at": "2024-05-16 13:27:09 UTC"
        },
        {
            "created_at": "2024-05-16 13:26:07 UTC",
            "failed": 0,
            "host": "host2.example.com,
            "id": 405,
            "othered": 0,
            "passed": 0,
            "updated_at": "2024-05-16 13:26:07 UTC"
        },
        {
            "created_at": "2024-05-16 13:25:07 UTC",
            "failed": 0,
            "host": "host3.example.com",
            "id": 406,
            "othered": 0,
            "passed": 0,
            "updated_at": "2024-05-16 13:25:07 UTC"
        },
        {
            "created_at": "2024-05-16 13:24:07 UTC",
            "failed": 0,
            "host": "host4.example.com",
            "id": 407,
            "othered": 0,
            "passed": 0,
            "updated_at": "2024-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://foreman.example.com/api/v2/compliance/arf_reports/405

    Example response:

    HTTP/1.1 200 OK
Date: Thu, 18 May 2024 07:14:36 GMT
Server: Apache/2.4.6 (Enterprise Linux)
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Foreman_version: 3.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
Example 1. Example BASH script to delete all OpenSCAP reports
#!/bin/bash

# this script removes all ARF reports from your Foreman server

# settings
USER="My_User_Name"
PASS="My_Password"
URI="https://foreman.example.com"

# check amount of reports
 while [ $(curl --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\total\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g") -gt 0 ]; do

# fetch reports
 for i in $(curl --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\id\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g")

# delete reports
  do
  curl --user $USER:$PASS --header "Content-Type: application/json" --request DELETE $URI/api/v2/compliance/arf_reports/$i
  done
done

Appendix A: API response codes

The Foreman API provides HTTP response status codes for API calls. The following codes are common for all resources in the Foreman API.

Table 1. API response codes
Response Explanation

200 OK

For a successful request action: show, index, update, or delete (GET, PUT, DELETE requests).

201 Created

For a successful create action (POST request).

301 Moved Permanently

Redirect when Foreman is restricted to use HTTPS and HTTP is attempted.

400 Bad Request

A required parameter is missing or the search query has invalid syntax.

401 Unauthorized

Failed to authorize the user, for example, due to incorrect credentials.

403 Forbidden

The user has insufficient permissions to perform the action or read the resource, or the action is unsupported in general.

404 Not Found

The record with the given ID does not exist. It can appear in show and delete actions when the requested record does not exist; or in create, update and delete actions when one of the associated records does not exist.

409 Conflict

Could not delete the record due to existing dependencies, for example, host groups that still contain hosts.

415 Unsupported Media Type

The content type of the HTTP request is not JSON.

422 Unprocessable Entity

Failed to create an entity due to some validation errors. Applies to create or update actions only.

500 Internal Server Error

Unexpected internal server error.

503 Service Unavailable

The server is not running.

Appendix B: Creating a complete permission table

Generate a complete permission table from the Foreman console to review all available permissions and actions on your Foreman.

Prerequisites

  • The foreman-console package is installed on Foreman server.

Procedure

  1. Start the Foreman console:

    # foreman-rake console

  2. Insert the following code into the console:

    f = File.open('/tmp/table.html', 'w')

result = Foreman::AccessControl.permissions {|a,b| a.security_block <=> b.security_block}.collect do |p|
      actions = p.actions.collect { |a| "<li>#{a}</li>" }
      "<tr><td>#{p.name}</td><td><ul>#{actions.join('')}</ul></td><td>#{p.resource_type}</td></tr>"
end.join("\n")

f.write("<table border=\"1\"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>\n")
f.write(result)
f.write("</table>\n")

    The above syntax creates a table of permissions and saves it to the /tmp/table.html file.

  3. Press Ctrl + D to exit the Foreman console.

  4. Open /tmp/table.html in a web browser to view the table.

Pre-release version Report issue