2. API methods to add a Host

Objective

Create a host with the R81.20 API using the SmartConsole CLI , Use the R81.20 Management API guide as a reference.

Instructions

Step

Instructions

1

From the Jump-Server , Open Chrome and navigate to (https://203.0.113.80/api_docs) to access the API reference or use the saved bookmark on Chrome.

2

Select Network Objects > Host > add host in the navigation tree on the left side of the page.

3

Notice the four options for what method is used to access the API.

The four methods are :

  1. SmartConsole CLI – Used in SmartConsole

  2. Mgmt_cli tool – Used from any Gaia or Windows system with the local mgmt_cli command

  3. Gaia CLI – used from within CliSH in Gaia to access the API

  4. Web Services – Restful access to the API – remember that we need GUI client access to use this method of the API

Each method is listed in the API guide.

Click SmartConsole CLI:

4

Review the options of how to add a host using the SmartConsole CLI.

Check the example at the bottom of the page :

Note - Only certain parameters are required for each command as noted in the API guide.

5

Move back to the SmartConsole and open Network Objects on the right side of the page.

6

Notice there are no hosts configured on the management server since there are no counts for hosts listed in this view.

7

Open the SmartConsole CLI from the left side of the SmartConsole – the icon is named Command Line.

Note -The Command Line option is not the Gaia Command Line. It is the SmartConsole CLI used with the API only!

8

In the SmartConsole CLI add a host with the following parameters :

  1. name : Task1host

  2. ip address : 99.99.99.99

    add host name Task1host ip-address 99.99.99.99 color blue

9

Review the host that was added using the Networks Objects on the right side of the screen.

Notice that a host is now listed on the object tree.

10

Now using the R81.20 API Guide, delete the host Task1host that was created using the SmartConsole CLI:

delete host name Task1host

Note - Remember each command has different required parameters. In the case of the delete command, the only required parameter is either name or UID!

11

Publish your changes using the publish button at the top of the SmartConsole.

All changes done with the SmartConsole CLI will use the publish/ discard options from SmartConsole.

Note - Using the publish command from the SmartConsole CLI is not supported. The only method to publish changes from the SmartConsole CLI is to use the Publish button within the SmartConsole.

Objective

Create a host with the API using mgmt_cli from the management server.

Use the R81.20 Management API guide as a reference.

Instructions

Step

Instructions

1

Using the R81.20 API Guide, review the command to add host using the mgmt_cli tool.

Note - Reminder - examples of each API command is listed at the bottom of each page and all four methods of using the API are listed.

2

Switch back to the SSH window to the R81.20 Management server ,

Add a host named Task2host with an ip address of 22.22.22.22:

mgmt_cli add host name Task2host ip-address 22.22.22.22

  1. Use the username api_user

  2. Use the password vpn123

  1. Notice that the publish operation happens automatically as part of this command.

  2. When a single API command or command without a session ID is run using the mgmt_cli an implicit publish will happen when the command completes.

3

Next delete the host. Use the API guide as a reference for removal.

This time pass the userid “api_user” to the command:

mgmt_cli delete host name Task2host -u api_user

4

Now run the same command to add the host, but use the following flags when running the command - “ -r true “:

mgmt_cli -r true add host name Task2host ip-address 22.22.22.22

Note - The –r true option allows the user to receive SuperUser permissions. No additional login credentials are required. This flag will only function if running on the local management server.

5

Delete the host Task2host using the mgmt_cli:

mgmt_cli -r true delete host name Task2host

Objective

Learn how to use the R81.20 Management API to add multiple elements from a CSV file.

To use CSV we utilize a batch function in the API to add multiple elements.

Instructions

Step

Instructions

1

In the SSH session of the management server move to the R8X_Mgmt_Scripts directory:

cd /home/admin/R8X_Mgmt_Scripts

2

Review the hosts.csv file by running the command :

cat hosts.csv

  1. The first line of the file describes the contents of the file and the data that will be run for each host.

  2. There are four items being configured for each host: Name, Ip-address, Color and Tags.

  3. When adding elements via CSV only one type of command is permitted per csv file.

    We cannot mix hosts, services, rules in the same file. To accomplish this type of task we would need to run each of them separately.

  4. Run the following to review the command that will be run the create the multiple hosts :

    cat addhost

  5. Run the command that will create the multiple hosts : 

    bash addhost

3

Review the SmartConsole and see the new hosts that were created :

4

Overlay the SSH session on top of the SmartConsole so you can see the hosts on the right of SmartConsole.

Watch the objects lock and disappear when the following command is run to remove the objects:

bash deletehost

Note - The mgmt_cli can be used in Gaia as well as on Windows.

Any SmartConsole install includes a portable version of mgmt_cli to access the R81 management API server.

Remember that access to the API could be restricted and can be setup to mirror the SmartConsole GUI client access.