Multi-Domain Management Commands and Utilities

In This Section: Managing Security through API and CLI Command Line Reference

Managing Security through API and CLI

You can configure and control the Management Server with the new command line tools and through web services. You must first configure the API server.

The API server runs scripts that automate daily tasks and integrate the Check Point solutions with third party systems such as virtualization servers, ticketing systems, and change management systems.

You can use these tools to run API scripts on the Management Server:

• Standalone management tool, included with SmartConsole. You can copy this tool to computers that run Windows or Gaia operating system.
  • mgmt_cli.exe (for Windows operating system)
  • mgmt_cli (for Gaia operating system)
• Web Services API that allows communication and data exchange between the clients and the Management Server over the HTTP protocol. It also lets other Check Point processes communicate with the Management Server over the HTTPS protocol.

All API clients use the same port as the Gaia Portal.

To learn more about the management APIs, to see code samples, and to take advantage of user forums, see:

• The Online Check Point Management API Reference Guide.
• The Developers Network section of CheckMates.

Configuring the API Server

To configure the API Server:

1. In SmartConsole, go to Manage & Settings > Blades.
2. In the Management API section, click Advanced Settings.

   The Management API Settings window opens.

3. Configure the Startup Settings and the Access Settings.

API Settings

Startup Settings

Select Automatic start to automatically start the API server when you start or reboot the Management Server.

The Automatic start option is activated by default during Management Server installation, if the Management Server has more than 4GB of RAM installed. If the Management Server has less than 4GB of RAM, the Automatic Start is deactivated.

If you change the Automatic start option:

1. Publish the session changes in SmartConsole.
2. Run the api restart command on the Management Server.

Access Settings

Select one of these options to configure which SmartConsole clients connect to the API server:

• Management server only - Only the Management Server itself can connect to the API Server. This option only lets you use the mgmt_cli utility to send API requests. You cannot use SmartConsole or web services to send API requests.
• All IP addresses that can be used for GUI clients - You can send API requests from all IP addresses that are defined as Trusted Clients in SmartConsole. This includes requests from SmartConsole, Web services and the mgmt_cli utility.
• All IP addresses - You can send API requests from all IP addresses. This includes requests from SmartConsole, Web services and the mgmt_cli utility.

Command Line Reference

This section includes documentation CLI Commands that are associated with Multi-Domain Management.

cpmiquerybin

cpmiquerybin connects to a specified database, runs a user-defined query and shows the query results. The results can be a collection of Firewall sets or a tab-delimited list of specified fields from each retrieved object. The default database of the query tool is based on the shell environment settings.

To connect to a Domain Server database, run mdsenv and define the necessary environment variables. Use the Domain Server name or IP address as the first parameter.

Note - The MISSING_ATTR string shows when you use an attribute name that does not exist in the objects in query result.

Syntax

cpmiquerybin <query_result_type> <database> <table> <query> [-a <attributes_list>]

Parameter	Description
<query_result_type>	Query result in one of these formats: attr – Returns values from one or more specified fields for each object. Use the -a parameter followed by a comma separated list of fields. object – display FW-1 sets containing data of each retrieved object.
<database>	Name of the database file in quotes. For example, "mdsdb". Use "" to run the query on the default database.
<table>	Name of the database table that contains the data.
<query>	One or more query strings in a comma separated list. Use the null ("") query to return all objects in the database table. You can use wildcard character (*) as a replacement for one or more matching characters in your query string.
-a <attributes_list>	If you use the query_result_type parameter, you must specify one or more attributes in a comma-delimited list (without spaces) of object fields. You can return all object names with the special string: __name__

You can see complete documentation of the cpmiquerybin utility, with the full query syntax, examples and a list of common attributes in sk65181.

Return Values

0 - Query returns data successfully
1 - Query does not return data or there is a query syntax error

Example:

# cpmiquerybin attr "" network_objects "" -a __name__

DMZZone

WirelessZone

ExternalZone

InternalZone

AuxiliaryNet

LocalMachine_All_Interfaces

CPDShield

InternalNet

LocalMachine

DMZNet

This example shows the names of the currently defined network objects.

mds_backup

mds_backup backs up binaries and data from a Multi-Domain Server to a user specified working directory. You then copy the backup files from the working directory to external storage. This command requires Multi-Domain Superuser privileges.

mds_backup runs the gtar and dump commands to backup all databases. The collected information is stored in one .tar file. The file name is a combination of the backup date and time and is saved in the current working directory. For example, 13Sep2015-141437.mdsbk.tar

Important - Starting from Take 245 of R80.10 Jumbo Hotfix Accumulator (PMTR-36614), the mds_backup command generates a file with the *.tar extension (<timestamp>mdsbk.tar) instead of the *.tgz extension (<timestamp>mdsbk.tgz).

To back up a Multi-Domain Server:

1. Run mds_backup from a location outside the product directory tree to be backed up. This becomes the working directory.
2. After the backup completes, copy the backup .tgz file, together with the mds_restore, gtar and gzip command files, to your external backup location.

Syntax

mds_backup -h

mds_backup [-g -b {-d <target_directory>} -s [-v] [-l]]

Argument	Description
-h	Shows help text.
-g	Executes without prompting to disconnect GUI clients.
-b	Batch mode - executes without asking anything (-g is implied).
-d	Target directory for the backup file. If not specified, the backup file is saved to the current directory. You cannot save the backup file to the root directory.
-v	"Dry run" - Show all files to be backed up, but does not perform the backup operation.
-l	Exclude logs from the backup.
-s	Stop Multi-Domain processes before the backup starts.

Notes:

• Do not create or delete Domains or Domain Servers until the backup operation completes.
• It is important not to run mds_backup from directories that will be backed up. For example, when backing up a Multi-Domain Server, do not run mds_backup from /opt/CPmds-<current_release> because it is a circular reference (backing up directory that you need to write into).
• Active log files are not backed up. This is necessary to prevent inconsistencies during the read-write operations.

  Best Practice - We recommend that you do a log switch before you start the backup procedure.

• You can back up the Multi-Domain Server configuration without the log files. This backup is typically significantly smaller than a full backup with logs. To back up without log files, add this line to the file $MDSDIR/conf/mds_exclude.dat configuration file:
  log/*

mds_restore

Use this command to restore a Multi-Domain Server that was backed up with mds_backup.

If the Multi-Domain Management environment has multiple Multi-Domain Servers, restore all Multi-Domain Servers at the same time.

Important - You must restore on the server that runs the same software version, from which you collected this backup. Example: If you collected a backup on a server with version "XX" and Jumbo Hotfix Accumulator Take "YY", then you must restore on a server with version "XX" and Jumbo Hotfix Accumulator Take "YY".

To restore a Multi-Domain Server:

1. Connect to the command line on the Multi-Domain Server.
2. Log in to the Expert mode.
3. Go to the directory where the backup file is located.
4. Run:

   mds_restore <backup_file>

5. If you restore a Multi-Domain Server to a new IP address, configure the new address.

mdsenv

Use mdsenv to set shell environment variables to run commands on a specified Domain Server. When run without an argument, the command sets the shell for Multi-Domain Server level commands (mdsstart, mdsstop, and so on).

Syntax

mdsenv [<name>]

parameter	Description
<name>	Domain Server name.

mdsquerydb

mdsquerydb is an advanced database query tool that lets administrators use shell scripts to get information from Check Point Security Management Server databases. Use mdsquerydb to get information from the Multi-Domain Server, Domain Server and global databases.

The system comes with pre-defined queries, defined in the $MDSDIR/confqueries.conf configuration file. Do not change or delete these queries.

Syntax

mdsquerydb <key_name> [-f <output_file_name>]

Parameter	Description
<key_name>	Query key, which must be defined in the pre-defined queries configuration file.
-f <output_file_name>	Send the query results to the specified file name. If this parameter is not specified, the data is sent to the standard output.

Pre-Defined Query Keys

Keys for Multi-Domain environment:

----------------------------------

GlobalNetworkObjects Get name and type of all global network objects

NetworkObjects Get all Domains' internal Check Point installed network objects

Domains Get names of all Domains Irit B comment from QA Draft

Administrators Get names of all Administrators

MDSs Get names and IPs of all MDSs

DomainManagementServers Get names of all Domain Servers

GuiClients Get names and IPs of all gui clients

CMAs Backwards Compatibility (DomainManagementServers)

Customers Backwards Compatibility (Domains)

Keys for Domain environment:

----------------------------

NetworkObjects Get name and type of all network objects

Gateways Get names and IPs of all gateways

Examples:

To retrieve list of all defined keys, run: # mdsquerydb

To send a list of Domains in the Multi-Domain Server database to the standard output, run:
# mdsenv
# mdsquerydb Domains

To send a list of network objects in the global database to /tmp/gateways.txt, run:
mdsenv
mdsquerydb NetworkObjects –f /tmp/gateways.txt

To get a list of gateway objects in the Domain Server DServer1,run:
mdsenv DServer1
mdsquerydb Gateways –f /tmp/gateways.txt

mdsstart

Use mdsstart to start the Multi-Domain Server and all Domain Servers and mdsstop to stop the Multi-Domain Server and all Domain Servers.

Syntax

mdsstart [-m|-s]

Parameter	Description
-m	Starts only the Multi-Domain Server and not the Domain Servers.
-s	Starts the Domain Servers sequentially. The system waits for each Domain Server to come up before it starts the next one.

You can decrease the amount of time it takes to start and stop the Multi-Domain Server when there are many Domain Servers. To do this, set the environment variable NUM_EXEC_SIMUL to a smaller number of Domain Servers that start or stop at the same time. By default, the system attempts to start or stop up to 10 Domain Servers at the same time.

mdsstat

mdsstat shows the status of processes on the Multi-Domain Server and Domain Servers. The status can be UP or Down.

Syntax

mdsstat [-h] [-m] [<name>]

Parameter	Description
-h	Displays help message.
-m	Test status for Multi-Domain Server only.
<name>	Enter the name of a Domain Server to show its status.

Status:

up: The process is up.
down: The process is down.
pnd: The process is pending initialization.
init: The process is initializing.
N/A: The process's PID is not yet available.
N/R: The process is not relevant for this Multi-Domain Server.

Example:

# mdsstat

+--------------------------------------------------------------------------------------+

| Processes status checking |

+-----+----------------+-----------------+------------+----------+----------+----------+

| Type| Name | IP address | FWM | FWD | CPD | CPCA |

+-----+----------------+-----------------+------------+----------+----------+----------+

| MDS | - | 192.168.3.101 | up 17284 | up 17266 | up 17251 | up 17753 |

+-----+----------------+-----------------+------------+----------+----------+----------+

| CMA |DOM211_Server | 192.168.3.211 | up 32227 | up 32212 | up 25725 | up 32482 |

| CMA |DOM212_Server | 192.168.3.212 | up 4248 | up 4184 | up 4094 | up 4441 |

+-----+----------------+-----------------+------------+----------+----------+----------+

| Total Domain Management Servers checked: 2 2 up 0 down |

| Tip: Run mdsstat -h for legend |

+--------------------------------------------------------------------------------------+

migrate_global_policies

This utility transfers (and upgrades, if necessary) the global configuration database from one Multi-Domain Server to another Multi-Domain Server. migrate_global_policies replaces all existing global configurations. Each existing global configuration is saved with a *.pre_migrate extension.

If you migrate only the global configurations (without the Domain Servers) to a new Multi-Domain Server, disable all Security Gateways that are enabled for global use.

Note - You can only use migrate_global_policies when the target Multi-Domain Server does not have global configurations defined.

You can migrate global Policies from these Multi-Domain Management versions:

• R75.x
• R76.x
• R77.x

You can only use migrate_global_policies to import files created with export_database from Multi-Domain Servers with the above versions. You cannot export an R80.x global configuration database and then use migrate_global_policies on an R80.x Multi-Domain Server.

Syntax

migrate_global_policies <path>

parameter	Description
<path>	The fully qualified path to the directory where the global policies files, originally exported from the source Multi-Domain Server ($MDSDIR/conf), are located.

Example

# migrate_global_policies /tmp/exported_global_db.22Jul2007-124547.tgz

threshold_config

Use threshold_config to configure Policy thresholds. You must be in expert mode to run this command. After you run threshold_config, follow the on-screen instructions to make selections and configure the global settings and each threshold.

Syntax

threshold_config

When you run threshold_config, you get these options:

• Show Policy name - Shows you the name configured for the threshold Policy.
• Set Policy name - Lets you set a name for the threshold Policy.
• Save Policy- Lets you save the Policy.
• Save Policy to file - Lets you export the Policy to a file.
• Load Policy from file - Lets you import a threshold Policy from a file.
• Configure global alert settings - Lets you configure global settings for how frequently alerts are sent and how many alerts are sent.
• Configure alert destinations - Lets you configure a location or locations where the SNMP alerts are sent.
• View thresholds overview - Shows a list of all thresholds that you can set.
• Configure thresholds - Open the list of threshold categories to let you select thresholds to configure.

Creating a Domain Server

Prerequisites

• Name or Identifier of the domain, for example MyDomain
• Name or Identifier of the new Domain Server, for example MyDMS
• IPv4 address for the new Domain Server
• IPv4 Address for the Multi-Domain Server
• The Multi-Domain Server username and password for a Multi-Domain Superuser who has permission to create the new Domain Server.

To create a new Domain Server:

1. Open a terminal emulation program (such as PuTTY).
2. Open an SSH connection to the Multi-Domain Server.
3. Log in with the superuser credentials.
4. Enter expert mode.
5. Run this command:

   mgmt_cli add domain name <domain_name> servers.ip address "<ipv4>" servers.name "<server_name>" servers.multi-domain-server "<mdm_name>"

   For Example:

   mgmt_cli add domain name "domain1" servers.ip-address "192.0.2.1" servers.name "domain1_ManagementServer_1" servers.multi-domain-server "primary_mdm"

   The Domain Server is created. Log in to 192.0.2.1 to configure the settings.