Firepower System Host Input API Guide v6.0
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- November 9, 2015
Chapter: Configuring Host Input Clients
Configuring Host Input Clients
In addition to accepting host input commands from users on the Management Center, the Management Center’s host input service also accepts batch import files from authenticated host input clients on external hosts. You can use a host input client to process import files created for the host input import tool and then send the data to the Management Center to add the information to your network map.
You can use the provided host input API reference client to process and send CSV data or to test your host input client connection to the Management Center.
Perform the following tasks to manage Management Center and input client interaction:
1.
Establish an authenticated connection to the Management Center.
See Registering the Host Input Client with the Management Center for information about generating authentication credentials to establish an authenticated connection to the Management Center.
2. Set up the reference client on the computer where you plan to run it. For more information, see Using the Host Input Reference Client.
For information on creating import files (also referred to as command files) that you will use your reference client to process, see Writing Host Input Import Files.
Registering the Host Input Client with the Management Center
Before you can use a host input client, you must register the computer on which the client runs with the Management Center. The Management Center then generates an authentication certificate, which you download to your client computer.
1. If domains have been created on your system, select the desired domain in the domain switcher. Clients using a certificate created for the Global domain or another parent domain will have permission to alter any leaf domain in that scope, but the import file must specify which domain. Clients using a certificate created for a leaf domain will only have permission to alter that leaf domain.
2. Select System > Integration > Host Input Client.
The Host Input Client page appears.
The Create Client page appears.
4. In the Hostname field, enter the host name or IP address of the host running the host input client.
Note: If you use a host name, the host input server must be able to resolve the host to an IP address. If you have not configured DNS resolution, you should configure it first or use an IP address.
5. If you want to encrypt the certificate file, enter a password in the Password field.
The host input service allows the client computer to access port 8307 on the Management Center and creates an authentication certificate to use during client-server authentication. The Host Input Client page re-appears, with the new client listed under Host Input Clients.
7. Click the download icon (
) next to the certificate file.
8. Save the certificate file to the directory used by your client computer for SSL authentication.
The client can now connect to the Management Center.
Note: To revoke access for a client, click the delete icon (
) next to the host you want to remove. Note that you do not need to restart the host input service on the Management Center; access is revoked immediately.
Connecting the Client to the Management Center
The host input service on the Management Center reads a version from the client when the client connects. If the client sends a version newer than the version of the server, the service rejects the connection.
In addition, during the initial exchange, the host input service communicates the maximum allowed data size per transaction to the client. If the client attempts to send a data block bigger than the maximum size, the server closes the connection.
Using the Host Input Reference Client
The reference client provided with the host input SDK is a set of sample client scripts and Perl modules that illustrate how you can use the host input API. You can run them to familiarize yourself with host input import, or you can use them to debug problems with installations of your custom-built client. You can also use one of the scripts to process a host input command file from the client.
For more information on setting up reference clients, see the following sections:
Setting Up the Host Input Reference Client
To use the host input reference client, you must first install the sample scripts and configure your client to fit the script requirements.
For more information, see the following sections:
- Understanding the Host Input Reference Client
- Configuring Communications for the Host Input Reference Client
- Loading General Prerequisites for the Host Input Reference Client
- Downloading and Unpacking the Host Input Reference Client
- Creating a Certificate for the Host Input Reference Client
Understanding the Host Input Reference Client
You can download the HostInputClientSDK.zip package, which contains the host input reference client, from the Cisco support site. The Host Input Reference Client Files lists the files included in the HostInputClientSDK.zip package.
Configuring Communications for the Host Input Reference Client
The reference client uses the Secure Sockets Layer (SSL) protocol for data communication. You must install OpenSSL on the computer you plan to use as a client and configure it appropriately for your environment.
1. Download OpenSSL from http://openssl.org/source/.
2. Unpack the source to /usr/local/src.
3. Configure the source by running the Configure script.
4. Make and install the compiled source.
Loading General Prerequisites for the Host Input Reference Client
Before you can run the host input reference client, you must install the IO::Socket::SSL Perl module on the client computer. You can install the module manually or use cpan to do so.
Note: If the Net::SSLeay module is not installed on the client computer, install that module as well. Net::SSLeay is required for communication with OpenSSL.
You also need to install and configure OpenSSL to support an SSL connection to the Management Center. For more information, see Configuring Communications for the Host Input Reference Client.
In addition, if you plan to use the Qualys plugin with the host input client, you must install the XML::Smart Perl module and its prerequisites. If you plan to use IPv6 to communicate between the client and the Management Center, you must also install the IO::Socket::INET6 Perl module.
Downloading and Unpacking the Host Input Reference Client
You can download the HostInputClientSDK.zip file that contains the host input reference client from the Support site.
Unpack the zip file to a computer running the Linux operating system, where you plan to run the client.
Creating a Certificate for the Host Input Reference Client
Before you can use the host input reference client, you need to create client certificate as described in Registering the Host Input Client with the Management Center. You must save that certificate file to the directory where you put the reference client.
To create a certificate for the reference client:
1. Create a client as described in Registering the Host Input Client with the Management Center.
2. Save the certificate file to the directory where you put the reference client.
Running the Host Input Reference Client
The Host Input Perl reference client scripts are designed for use on an operating system with the Linux kernel but should work on any POSIX-based operating system, as long as the client machine meets the prerequisites defined in Setting Up the Host Input Reference Client.
You can use the reference client to import CSV data from a remote client to the network map on a Management Center.
Use the following syntax to run the sf_host_input_agent.pl script:
For example, to import using a CSV file named csv_file.txt to a Management Center with an IP address of 10.10.0.4 and with debug logging to HostInput.log log file:
./sf_host_input_agent.pl -server=10.10.0.4 -level=3 -logfile=HostInput.log -pl -pluginfo=cvs_file.txt csv
Feedback