Gaia API Proxy

Check Point products support API commands. See the Check Point API Reference.

With the Gaia API Proxy feature on a Management Server, you run the Gaia API commands on managed Security Gateways and Cluster Members:

  1. An administrator connects with an API Client to a Management Server.

  2. From the Management Server, an administrator runs the Gaia API commands on managed Security Gateways and Cluster Members.

The Gaia API Proxy feature on the R82 Management Server works with all managed Security Gateways and Cluster Members that support the Gaia API.

Example diagram

Item

Description

1

An API Client

2

A Management Server with the Gaia API Proxy feature

3

A managed Security Gateway

4

A managed ClusterXL

A

Management API communication

B

Gaia API communication

Important - Scalable Platforms (ElasticXL, Maestro, and Chassis) do not support this feature (Known Limitation MBS-10832).

Workflow:

  1. When you work with an API Client, run the Check Point API "login" command to log in to the Management Server (see the Check Point Management API Reference).

    Important - The administrator that logs in must have the Run One Time Script permission enabled in the assigned permission profile:

    1. Connect with SmartConsole to the Management Server.

    2. From the left navigation panel, click Manage & Settings.

    3. In the top section, click Permissions & Administrators > Permission Profiles.

    4. Open the applicable permission profile.

    5. From the left tree, click Overview.

      • If you selected Read/Write All, then click Cancel.

        The required permission is already enabled.

      • If you selected Customized, then:

        1. From the left tree, click Gateways.

        2. In the Scripts section, select Run One Time Script.

        3. Click OK.

        4. Publish the SmartConsole session

  2. The Management API "login" command returns the Session Unique Identifier (SID) token.

    In the same API Client, use this SID token in the "X-chkp-sid" field of the Gaia API commands you run on managed Security Gateways and Cluster Members.

    Gaia API Syntax:

    POST https://<IP Address of Management Server>/web_api/gaia-api/<Gaia API Version>/<Gaia API Command>

    See the Check Point Gaia API Reference.

    The body of the Gaia API command must identify the managed Security Gateway or Cluster Member by one of these parameters:

    • Object name

    • Object primary IP address

    • Object UID

  3. The Gaia API Proxy on the Management Server interprets the Gaia API command and logs in to the specified Security Gateway or Cluster Member.

    1. This login returns the SID for the Security Gateway or Cluster Member.

    2. The Gaia API Proxy uses this SID to run the Gaia API commands.

    3. The Gaia API Proxy saves this SID in its database:

      • The SID timeout is 580 seconds on the Management Server.

      • The SID timeout is 10 minutes on a Security Gateway or Cluster Member.

    • To increase performance, the Gaia API Proxy saves the response in the Gaia API Proxy cache on the Management Server.

    • If the Gaia API Proxy gets the same Gaia API request during the cache timeout, it returns the Gaia API response from its cache and updates the cache.

    • An administrator can configure these cache parameters in the $FWDIR/api/conf/cache.conf file on the Management Server:

      Note - After you change the $FWDIR/api/conf/cache.conf file, you must reload the API server configuration with the "api reconf" command in the Expert mode.

      Parameter

      Accepted Values

      Description

      timeout

      0, or greater

      Specifies the time, after which the next Gaia API command triggers a cache update for that Gaia API command:

      • 0 - The Gaia API proxy does not use cache

      • <integer> - The Gaia API proxy saves the Gaia API responses in its cache for the specified number of seconds (default: 60 seconds)

      total_gateways

      integer

      Specifies the number of unique Security Gateways and Cluster Members, from which to save the Gaia API responses.

      maximum_entries

      integer

      Specifies the number of unique Gaia API commands to save for each Security Gateway and Cluster Member.

Important - The Gaia API Proxy sends Gaia API command over HTTPS. The Access Control policy for the Security Gateway or ClusterXL must explicitly allow HTTPS traffic from the Management Server to the Security Gateway or Cluster Members.

Examples

In this example, we identify the managed Security Gateway by the object primary IP address.

Request

POST https://<IP Address of Management Server>/gaia-api/show-hostname
Content-Type: application/json
X-chkp-sid: <Session ID>
{
  "target" : "192.168.1.1"
}

Response

{
  "command-name" : "show-hostname",
  "response-message" : {
    "name" : "gw-832546"
  }
}

In this example, we identify the managed Security Gateway by the object name.

Request

POST https://<IP Address of Management Server>/gaia-api/v1.4/show-interfaces
Content-Type: application/json
X-chkp-sid: <Session ID>
{
  "target" : "gw-832546",
  "name" : "eth0"
}

Response

{
  "command-name" : "v1.4/show-interfaces",
  "response-message" : {
    "ipv6-local-link-address": "Not Configured",
    "type": "physical",
    "name": "eth0",
    "ipv6-mask-length": "Not-Configured",
    "ipv6-address": "Not-Configured",
    "ipv6-autoconfig": "Not configured",
    "ipv4-address": "192.168.1.1",
    "enabled": true,
    "comments": "",
    "ipv4-mask-length": "24"
  }
}

In this example, we identify the managed Security Gateway by the object UID.

Request

POST https://<IP Address of Management Server>/gaia-api/v1.4/show-diagnostics
Content-Type: application/json
X-chkp-sid: <Session ID>
{
  "target" : "52048978-c507-8243-9d84-074d11154616",
  "category" : "os",
  "topic" : "disk"
}

Response

{
  "command-name" : "v1.4/show-diagnostics",
  "response-message" : {
    "to": 3,
    "total": 3,
    "from": 1,
    "objects": [
      {
      "total": "34342961152",
      "partition": "/",
      "used": "5718065152",
      "free": "28624896000"
      },
      {
      "total": "304624640",
      "partition": "/boot",
      "used": "26991616",
      "free": "277633024"
      },
      {
      "total": "34342961152",
      "partition": "/var/log",
      "used": "455684096",
      "free": "33887277056"
      }
    ]
  }
}