API

You can update the configuration settings, such as rules and policies, using the Application Programming Interface (API).

You can add, update, or delete configurations fully or partially.

You make changes to the XML strings or the .xml file.

You can apply the same configuration on more than one firewall using the API interface. You won't have to make changes to the individual modules and objects on each firewall's web admin console.

  • To use API configuration, go to Backup and firmware > API.
  • For details of the attributes to use in XML strings, download the API help file.

    Extract the file, and click index.html.

You can use one of the following methods to update the configuration:

XML strings: Use the strings to make changes in individual rules, policies, settings, or objects. To know more, see How to use API.

You can enter the XML string in one of the following locations:
  • On the command-line interface of XG Firewall. Alternatively, use the operating system of the endpoint device from which you access the XG Firewall console.
  • In a browser's address bar. All leading browsers support XML strings.
  • In applications, such as Postman.

The .xml file: Use the file to make extensive changes to the configuration. Go to Backup and firmware > Import export, and export the configuration fully or partially. Extract the .xml file from the .tar file, and make the changes. Convert it to a .tar file again, and import the .tar file. For details, see Import export.

API configuration

Setting

Description

API configuration

Select to allow administrators with permissions to get or set the configuration using the API.

You need to give read-write permissions to allow the administrator to make configuration changes.

To create an administrator profile with the read-write permissions, go to Profiles > Device access.

We recommend that you give read-write permissions only for the required objects and settings.

To apply the profile to an administrator, go to Authentication > Users.

Allowed IP address

IP addresses of hosts from which you can make the changes.

To get your IP address, search online. Alternatively, sign in to the web admin console. Go to Log viewer, select Admin from the list, and see the source IP address for your sign-in.

XML string and components

The XML string must contain the API controller, administrator sign-in request, and the configuration request. The following table shows the details of these components:

Component

Description

API controller string

https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add XML request here>

<Firewall IP>: IP address or hostname of XG Firewall.

<port>: Admin console HTTPS port you configured on Administration > Admin settings.

Administrator sign-in request

<Request><Login><Username>admin</Username><Password>1234</Password></Login>

Configuration requests

Get the configuration:

<Get><Attribute></Attribute></Get>

Add or update the configuration:

<Set><Attribute></Attribute></Set>

Delete the configuration:

<Remove><Attribute></Attribute><Remove>

For browsers, use the following XML string:

https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>

For the CLI, use the following XML string:

curl -k "https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>"

Examples of configuration requests:

Get request:

https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Get><IPHost><Name></Name><IPFamily></IPFamily><HostType></HostType><IPAddress></IPAddress></IPHost>
</Get></Request>

Set request:

https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType>
<IPAddress>198.1.2.1</IPAddress></IPHost></Set></Request>

Remove request:

https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Remove><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType>
<IPAddress>198.1.2.1</IPAddress></IPHost></Remove></Request>

XML tags and attributes

XML tags

Description

<Request>

Used for sending the XML request.

Attribute: API version

Example:

<Request APIVersion="1800.1" IPS_CAT_VER="1">
    <Login>
        <Username>admin</Username>
        <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
     </Login>
</Request>

<Login>

Authenticates the administrator.

Example:

<Login>
    <Username>admin</Username>
    <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
</Login>
<Username>

Administrator's username.

Example:

<Username>admin</Username>
<Password>

Administrator's password.

Example:

<Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>

You can't use the encrypted passwords in the .csv file exported from Authentication > Users. Use the plain text password or the encrypted password in the .xml file exported from Import export.

<Get>

Gets information for the tag you specify. For the attributes, see API help.

Example:

<Request>
    <Login>
        <Username>admin</Username>
        <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
     </Login>
     <Get>
        <IPHost></IPHost>
     </Get>
</Request>
<Set>

Adds or updates based on the tag you specify. For the attributes, see API help.

<Request>
    <Login>
        <Username>admin</Username>
        <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
    </Login>
    <Set operation="add">
        <IPHost>
            <Name>CustomIPHostTypeIPV4</Name>
            <IPFamily>IPv4</IPFamily>
            <HostType>IP</HostType>
            <IPAddress>1.1.1.1</IPAddress>
        </IPHost>
    </Set>
</Request>

If you don't enter “operation” and its value ("add" or "update"), XG Firewall adds the configuration. If the configuration exists, it updates the configuration.

<Remove>

Deletes the configuration. For the attributes, see API help.

<Request>
    <Login>
        <Username>admin</Username>
        <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
    </Login>
    <Remove>
        <IPHost>
            <Name>CustomIPHostTypeIPV4</Name>
        </IPHost>
    </Remove>
</Request>
<Filter>
<Key>

Filter gets data for the criteria you specify in the tag <Key>. You can only apply a filter to the attribute Name.

Use <Key> within the <Filter> tag to specify the filter key and filter criteria.

<Request>
    <Login>
        <Username>admin</Username>
        <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>
    </Login>
    <Get>
        <IPHost>
            <Filter>
                <key name="Name" criteria="like">CustomIPHostTypeIPV4</key>
            </Filter>
        </IPHost>
    </Get>
</Request>
<Response>

Shows the response for your request.

Attribute: APIVersion

Attribute value: The response tag shows the active firmware API version. Configuration tags show the value you specified in the XML request.

Example:

<Response APIVersion="1800.1" IPS_CAT_VER="1">
    <Login>
        <status>Authentication Successful</status>
    </Login>
    <IPHost transactionid="">
        <Status code="200">Configuration applied successfully.</Status>
    </IPHost>
</Response>
<Status>

Shows the configuration status based on the code.

Attribute: Status code

Attribute value: Code number

Example:

<Response APIVersion="1800.1" IPS_CAT_VER="1">
     <Login>
          <status>Authetication Successful</status>
     </Login>
     <IPHost transactionid="">
          <Status code="200">Configuration applied successfully.</Status>
     </IPHost>
</Response>

For the status codes, see API help.

Download the API help file

The API help shows the tags, attributes, and status codes. To see these, you must do the following:
  1. Download the API help for your firmware version.
  2. Extract the file and click index.html.


  3. The home page shows the XML tags, attributes, and some status codes. For details about how to format the XML requests, scroll down the API help page.
  4. The left menu and the attributes for each module are similar to the web admin console. If you need more details about an attribute, see the corresponding help page.

API explorer

You can sign in and sign out users using the API.

When you sign in a user using API, in Current activities > Live users, the user's client type shows API client.

<Request><LiveUserLogin><UserName>sophos</UserName><Password>sophos</Password><IPAddress>10.21.18.15</IPAddress>
<MacAddress>00:0C:29:2D:D3:AC</MacAddress> </LiveUserLogin></Request>
<Request><LiveUserLogout><Admin><UserName>admin</UserName><Password>admin</Password></Admin><UserName>sophos</UserName>
<IPAddress>10.21.18.15</IPAddress></LiveUserLogout></Request>

Example:

https://<XG Firewall IP address>:4444/webconsole/APIController?reqxml=<Request><LiveUserLogin><UserName>sophos
</UserName><Password>sophos</Password><IPAddress>10.21.18.15</IPAddress><MacAddress>00:0C:29:2D:D3:AC</MacAddress>
</LiveUserLogin></Request>