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.
This chapter describes the scripting interface that ACS 5.8.1 provides to perform bulk operations on ACS objects using the Import and Export features.
ACS provides the import and export functionalities through the web interface (graphical user interface) as well as the CLI. ACS exposes these functionalities through the CLI to enable you to create custom shell scripts for bulk operations on ACS objects. The import-data command allows you to:
The import and export functionalities in ACS 5.8.1 allow you to perform bulk operations such as Create, Update, and Delete on ACS objects and provide a migration path for customers migrating from ACS 4. x releases to ACS 5.8.1.
You can integrate ACS with any of your repositories and import data into ACS through automated scripts, using the Import and Export features. You can also encrypt the .csv file before you transfer the file for additional security, or, optionally, use Secure File Transfer Protocol (SFTP).
You can create a scheduled command that looks for a file with a fixed name in the repository to perform bulk operations. This option provides the functionality that was available in ACS 4.x releases.
ACS processes the import and export requests in a queue. Only one process can run at a time. When you use the ACS web interface for importing and exporting, you cannot manually control the queue.
ACS processes the queue in sequence. However, you can use the CLI to manage the import and export processes in ACS. The ACS CLI allows you to view the status of the queue and terminate the processes that are in the queue.
This chapter contains the following sections:
n Understanding Import and Export in ACS
n Using Shell Scripts to Perform Bulk Operations
You can use the import functionality in ACS to add, update, or delete multiple ACS objects at the same time. ACS uses a comma-separated values (CSV) file to perform these bulk operations. This .csv file is called an import file.
ACS provides a separate .csv template for Add, Update, and Delete operations for each ACS object. The first record in the .csv file is the header record from the template that contains column (field) names. You must download these templates from the ACS web interface. The header record from the template must be included in the first row of any .csv file that you import.
You cannot use the same template to import all ACS objects. You must download the template that is designed for each ACS object and use the corresponding template while importing the objects.
You can use the export functionality to create a .csv file that contains all the records of a particular object type that are available in the ACS internal store.
You must have CLI administrator-level access to perform import and export operations. Additionally:
n To import ACS configuration data, you need CRUD permissions for the specific configuration object.
n To export data to a remote repository, you need read permission for the specific configuration object.
n Importing ACS Objects Through the CLI
n Exporting ACS Objects Through the CLI
n Viewing the Status of Import and Export Processes
n Terminating Import and Export Processes
You can import ACS objects from the ACS Configuration mode. You use the import-data command to perform the Import operation. This command takes the following arguments:
n Name of the remote repository where the import file resides. See Creating Import Files, for information on how to create the import file.
n Type of ACS object that the import file contains.
ACS obtains the .csv file from the remote repository and processes the file. You can query ACS for the status of the import process using the import-export-status command. After the import process is complete, ACS generates a status file in the remote repository that includes any errors that ACS identified during this process.
For additional security during the import process, you have the option of encrypting the import file and using a secured remote repository for the import operation.
Also, the import process sometimes can run into errors. You can specify whether you want to terminate the import process or continue it until it is complete.
Note: If you choose to use a secured remote repository for import, you must specify SFTP as the repository value.
For example, to add internal user records to an existing identity store, from the ACS CLI, enter:
import-data add user repository file-name result-file-name {abort-on-error | cont-on-error} {full | none | only-sec-repo | only-sec-files} secret-phrase
repository —Name of the remote repository from which to import the ACS objects, in this case, the internal users.
file-name —Name of the import file in the remote repository.
result-file-name —Name of the file that contains the results of the import operation. This file is available in the remote repository when the import process completes or is terminated.
abort-on-error —Aborts the import operation if an error occurs during the import process.
cont-on-error —Ignores any errors that occur during the import process and continues to import the rest of the object.
full —Encrypts the import file using the GNU Privacy Guard (GPG) encryption mechanism and uses secured remote repository to import the file. If you specify the security type as full, you must specify SFTP as the repository value.
none —Neither encrypts the import file nor uses the secured remote repository for import.
secret phrase —Provide the secret phrase to decrypt the import file. If you specify the security type as full or only-sec-files, you must specify the secret phrase.
only-sec-repo —Uses the secured remote repository to import the file. If you specify the security type as only-sec-repo, you must specify SFTP as the repository value.
only-sec-files —Encrypts the import file using GPG encryption mechanism.
For more information on the import-data command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.1 .
You can export a list of ACS objects in a .csv file from ACS to your local drive. You can perform this operation from the ACS Configuration mode, using the export-data command. This command takes the following arguments:
n Name of the remote repository to which the .csv file should be downloaded after the export process is complete.
When ACS processes your export request, you can enter a command to query the progress of the export. After the export process is complete, the .csv file that is available in your remote repository should contain all the object records that exist in the ACS internal store.
Note: When you export ACS objects through the web interface, use the available filters to export a subset of the records.
For additional security during the export process, you have the option of encrypting the export file and using a secured remote repository for the export operation.
Note: If you choose to use a secured remote repository for export, you must specify SFTP as the repository value.
For example, to export internal user records, from the ACS CLI, enter:
export-data user repository file-name result-file-name {full | none | only-sec-repo | only-sec-files} secret-phrase
repository —Name of the remote repository to which to export the ACS objects, in this case, the internal users.
file-name —Name of the export file in the remote repository.
result-file-name —Name of the file that contains the results of the export operation. This file is available in the remote repository when the export process completes.
full —Encrypts the export file using the GPG encryption mechanism and uses secured remote repository to export the file. If you specify the security type as full, you must specify SFTP as the repository value.
none —Neither encrypts the export file nor uses the secured remote repository for export.
secret phrase —Provide a secret phrase to encrypt the export file. If you specify the security type as full or only-sec-files, you must specify the secret phrase.
only-sec-repo —Uses the secured remote repository to export the file. If you specify the security type as only-sec-repo, you must specify SFTP as the repository value.
only-sec-files —Encrypts the export file using GPG encryption mechanism.
For more information on the export-data command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.1 .
You can view the status of the import and export processes in ACS using the import-export-status command. Use this command to view the status of running import and export processes and to verify whether there are any pending processes.
You must run the import-export-status command from the ACS Configuration mode. Any user, irrespective of role, can issue this command.
import-export-status { current | all | id id }
current —Displays the status of the currently running processes.
all —Displays the status of all the import and export processes, including any pending processes.
id —Displays the import or export status, based on a particular process that is specified by the process ID.
For more information on the import-export-status command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.1 .
You can use the import-export-abort command to terminate all import and export processes, or process that are currently running or queued. You must run the import-export-abort command from the ACS Configuration mode.
Only the super administrator can simultaneously terminate a running process and all pending import and export processes. However, a user who owns a particular import or export process can terminate that particular process by using the process ID, or by stopping the process when it is running.
import-export-abort { running | all | id id }
current —Aborts any import or export process that is running currently.
all —Aborts all the import and export processes in the queue.
id —Aborts the import or export process, based on the process ID that you specify.
For more information on the import-export-abort command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.1 .
While ACS 5.8.1 allows you to perform bulk operations (Add, Update, Delete) on ACS objects using the import functionality, you cannot import all ACS objects. The import functionality in ACS 5.8.1 supports the following ACS objects:
Table 1 lists the ACS objects, their properties, and the property data types.
Fields that are optional can be left empty and ACS substitutes the default values for those fields.
For example, when fields that are related to a hierarchy are left blank, ACS assigns the value of the root node in the hierarchy. For network devices, if TrustSec is enabled, all related configuration fields are set to default values.
Note: You can export Administrators from the CLI as well as the ACS user interface. To export Administrators from the ACS user interface, use the export button available in the Administrator Accounts page. To export Administrators from the CLI, use the export-data command. For more information on the export-data command, see CLI Reference Guide for Cisco Secure Access Control System 5.8.1.
Note: You can export message catalog from the CLI as well as the ACS user interface. To export message catalog from the ACS user interface, use the export button available in the System Administration > Configuration > Log Configuration > Log Message Catalog page. To export message catalog from the CLI, use the export-message-catalog command.
This section describes how to create the csv file for performing bulk operations on ACS objects. You can download the appropriate template for each of the objects. This section contains the following:
n Downloading the Template from the Web Interface
n Understanding the CSV Templates
Before you can create the import file, you must download the import file templates from the ACS web interface.
To download the import file templates for adding internal users:
1. Log into the ACS 5.8.1 web interface.
2. Choose Users and Identity Stores > Internal Identity Stores > Users .
The File Operations wizard appears.
4. Choose any one of the following:
n Add—Adds users to the existing list. This option does not modify the existing list. Instead, it performs an append operation.
n Update—Updates the existing internal user list.
n Delete—Deletes the list of users in the import file from the internal identity store.
6. Click Download Add Template .
7. Click Save to save the template to your local disk.
The following list gives you the location from which you can get the appropriate template for each of the objects:
n User— Users and Identity Stores > Internal Identity Stores > Users
n Hosts— Users and Identity Stores > Internal Identity Stores > Hosts
n Network Device— Network Resources > Network Devices and AAA Clients
n Identity Group— Users and Identity Stores > Identity Groups
— Location— Network Resources > Network Device Groups > Location
— Device Type— Network Resources > Network Device Groups > Device Type
n Downloadable ACLs— Policy Elements > Authorization and Permissions > Named Permission Objects > Downloadable ACLs
n Command Set— Policy Elements > Authorization and Permissions > Device Administration > Command Sets
Follow the procedure described in this section to download the appropriate template for your object.
You can open your CSV template in Microsoft Excel or any other spreadsheet application and save the template to your local disk as a .csv file. The .csv template contains a header row that lists the properties of the corresponding ACS object.
For example, the internal user Add template contains the fields described in Table 2:
Each row of the .csv file corresponds to one internal user record. You must enter the values into the .csv file and save it before you can import the users into ACS. See Creating the Import File for more information on how to create the import file.
This example is based on the internal user Add template. For the other ACS object templates, the header row contains the properties described in Table 1 for that object.
After you download the import file template to your local disk, enter the records that you want to import into ACS in the format specified in the template. After you enter all records into the .csv file, you can proceed with the import function. The import process involves the following:
n Adding Records to the ACS Internal Store
When you add records to the ACS internal store, you add the records to the existing list. This is an append operation, in which the records in the .csv file are added to the list that exists in ACS.
To add internal user records to the Add template:
1. Download the internal user Add template. See Downloading the Template from the Web Interface for more information.
2. Open the internal user Add template in Microsoft Excel or any other spreadsheet application. See Table 1 for a description of the fields in the header row of the template.
3. Enter the internal user information. Each row of the .csv template corresponds to one user record.
Figure 1 Figure 1 shows a sample Add Users import file.
Figure 1 Add Users – Import File
When you update the records in the ACS store, the import process overwrites the existing records in the internal store with the records from the .csv file. This operation replaces the records that exist in ACS with the records from the .csv files.
The Update operation is similar to the Add operation except for one additional column that you can add to the Update templates.
The Update template can contain an Updated Name column for internal users and other ACS objects, and an Updated MAC address column for the internal hosts. The name shown in the Updated Name column replaces the name in the ACS identity store.
Instead of downloading the update template for each of the ACS objects, you can use the export file of that object, retain the header row, and update the data to create your updated .csv file.
To add an updated name or MAC address to the ACS objects, you must download and use the particular update template. Also, for the NDGs, the export template contains only the NDG name, so in order to update any other property, you must download and use the NDG update template.
Figure 2 shows a sample import file that updates existing user records.
Figure 2 Update Users–Import File
Note: The second column, Updated name, is the additional column that you can add to the Update template. Also, the password value and the enabled password value are not mandatory in the case of an update operation for the user object.
You can use this option to delete a subset of records from the ACS internal store. The records that are present in the .csv file that you import are deleted from the ACS internal store. The Delete template contains only the key column to identify the records that must be deleted.
For example, to delete a set of internal users from the ACS internal identity store, download the internal user Delete template and add the list of users that you want to delete to this Import file. Figure 3 shows a sample Import file that deletes internal user records.
Note: To delete all users, you can export all users and then use the export file as your import file to delete users.
Figure 3 Delete Users – Import File
You can write custom shell scripts that use the import and export CLI commands to perform bulk operations. The ACS web interface provides a sample Python script. To download this sample script:
1. Log into the ACS web interface.
2. Choose System Administration > Downloads > Scripts .
The downloadable package consists of: