Management API Command-Line Tool

This tool uses the Management API to add URLs and IP addresses (IPv4 and IPv6,
including ranges) to API-managed categories.

URLs and IP addresses are generated in a basic text file with a unique entry
on each line.

* A URL, at a minimum, needs to include the hostname. 

* If the protocol for any entry (http, https, ftp) is not provided, then 3
  entries, one for each protocol, are automatically created in the database.
  For example, if you add www.abc.com, the following URLs are added:
    http://www.abc.com
    https://www.abc.com
    ftp://www.abc.com

1. Overview:
   
   Use the scripts provided to generate sample lists of URLs and IP addresses
   and add them to API-managed categories.

2. Description:

       Name
          Managment API Command-Line Tool

       Syntax
          python policyapiservercli.py [-s hostname/ip] [-p port] [-u username] 
                 [-pw password] [-cat] [-inputUrlFile] [-inputIpFile]

       Default values
          hostname = localhost
          port = 15873
       
       Parameters
        -s      Hostname or IP address of the Management API (remote or local)
        
                * If the Management API is on another machine, provide the 
                  Policy Broker hostname or IP address.
                * If the Management API is on the current machine, the hostname
                  or IP address can be omitted.
            
        -p      Port number that the Management API uses for TRITON Manager
                communication
                
                If the default port was used when installing TRITON Manager,
                this parameter can be omitted.

        -u      The username for the Management API account, set in TRITON 
                Manager

        -pw     The password for the Management API account, set in TRITON
                Manager

        -cat    The name of the API-managed category to which the URLs or 
                IP addresses will be added

        -d      Used to delete the specified URLs or IP addresses, rather than
                adding them

        -inputUrlFile       Path to a ".txt" file containing one or more URLs,
                            with one URL per line
                            
                            The tool does not check the URL formatting. It is 
                            the administrator's responsibility to provide valid
                            URLs.

        -inputIpFile        Path to a ".txt" file containing one or more IP 
                            addresses or ranges, one per line
                            
                            The tool does not check IP address formatting. It 
                            is the administrator's responsibility to provide
                            valid IP addresses. 

    Administrators can use the tool multiple times to add URLs and IP addresses
    to a category. Each call appends the URLs/IP addresses in the file to the 
    existing ones in the category. URLs/IP addresses are not checked to 
    determine if they have already been added to the system. This means that
    duplicates will occur if the same input file is run multiple times.
    
    When adding or removing URLs, IP addresses, or IP address ranges, if the 
    specified API-managed category does not already exist, it is created.
    
3. Examples:

    a) /bin>python generate/ips.py
       Use this script to generate a sample IP address input file.

    b) /bin>python generate/urls.py
       Use this script to generate a sample URL input file.

    c) /bin>python policy_api_server.py -inputUrlFile 1000_urls.txt -u testuser -pw PassWord!1 -cat Education
       This script adds 1000 URLs to an API-managed category called Education.
   
    d) /bin>python policy_api_server.py -inputUrlFile 1000_urls.txt -inputIpFile 1000_ip4.txt -u testuser -pw PassWord!1 -cat Education
       This script adds 1000 URLs and IPV4 addresses to an API-managed category
       called Education.

    e) /bin>python policy_api_server.py -inputIpFile 1000_ip6_ranges.txt -u testuser -pw PassWord!1 -cat Education
       This script addes 1000 IPV6 ranges an API-managed category called 
       Education.

    f) /bin>python policy_api_server.py -inputUrlFile 1000_urls.txt -u testuser -pw PassWord!1 -cat Education -d
       This script removes the 1000 URLs added in c) above from the Education
       category.

4. Recommendation:

   Policy enforcement for URLs and IP addresses in API-managed categories
   begins when a database containing the URLs and IP addresses is built and
   loaded. As a best practice, poll the status of the API periodically after
   committing a transaction to see if the build and load process has been 
   completed. This will also reveal any errors that happened during the commit
   process.
      
   Refer to the example function "wait_for_db_build" to see how this works.
