Skip to main content

What's New and Release Notes for 26.x

CLI Tool Tutorials

This section provides several hands-on exercises that demonstrate step-by-step how to perform common tasks using the CLI Tool.

How to Import Traffic Flow Summaries

Static Illumination provides “moment-in-time” visibility of inter-workload traffic. This visibility is useful to model policies, to look for specious traffic flows, and to ensure that metadata for labels is accurate.

Goal

Load workload and traffic data needed for analysis with static Illumination.

Setup

This tutorial relies on the following data to import.

  • 1,000 workloads defined in the file bulkworkloads-1000.csv, which has the following columns:

    hostname,ips,os_type
10.14.59.8.netstat,10.14.59.8,linux
10.4.78.178.netstat,10.4.78.178,linux
10.37.134.179.netstat,10.37.134.179,linux
...

  • 1,000,000 traffic flows defined in the CSV file traffic.clean-1m.csv, which has the following columns:

    src_ip,dst_ip,dst_port,proto
10.40.113.86,10.14.59.8,10050,6
10.14.59.8,10.8.251.138,8080,6
10.40.113.124,10.14.59.8,22,6
...
Steps

The workflow is authenticated to the PCE and run two ilo bulk_upload_csv commands.

  1. Authenticate to the PCE via API key or explicit login.

  2. Load the workload data:

    ilo workload bulk_upload_csv --file bulkworkloads-1000.csv

  3. Load the traffic flow data:

    ilo traffic bulk_upload_csv --file traffic.clean-1m.csv
Results

The data from the CSV files are uploaded.

How to Create Kerberos-Authenticated Workloads

This tutorial describes how to create workloads that use Kerberos for authentication. The tutorial makes the following assumptions:

  • This tutorial assumes that you already have your Kerberos implementation in place.

  • As Kerberos requires, the Kerberos realm name is shown in all capital letters as MYREALM.

  • VEN environment variables must be set before VEN installation. Environment variables for Linux are detailed in the VEN Installation and Upgrade Guide.

Goals

  • Create two workloads on Linux that are authenticated by Kerberos.

  • Set the workloads' modes to idle and illuminated.

Setup

The key data for using the ilo command to create these workloads are the name of the Kerberos realm and the Service Principle Name (SPN).

Steps

The workflow is authenticate, run two workload create commands that set the workloads' modes, set the VEN environment variables, install the VEN, and run two Kerberos kinit commands to get Kerberos tickets for the workloads.

  1. Authenticate to the PCE via API key or explicit login.

  2. Create Kerberos-authenticated myWorkload1 and set its mode to idle:

    ilo workload create --hostname myPCE.BigCo.com --name myWorkload1 --service-principal-name host/myKerberosTicketGrantingServer@MYREALM --agent/config/mode idle

    For information about how the mode is a nested field, see Nested Resource Fields and Wildcards.

  3. Create Kerberos-authenticated myWorkload2 and set its mode to illuminated:

    ilo workload create --hostname myPCE.BigCo.com --name myWorkload2 --service-principal-name host/myKerberosTicketGrantingServer@MYREALM --agent/config/mode illuminated

  4. Before installation, set VEN environment variables:

    # Activate on installation
VEN_INSTALL_ACTION=activate
# FQDN and port PCE to pair with
VEN_MANAGEMENT_SERVER=myPCE.BigCo.com:8443
# Kerberos Service Principal Name
VEN_KERBEROS_MANAGEMENT_SERVER_SPN=host/myKerberosTicketGrantingServer
# Path to Kerberos shared object library
VEN_KERBEROS_LIBRARY_PATH=/usr/lib/libgssapi_krb5.so

  5. Install the Linux VEN:

    rpm -ivh illumio-ven*.rpm

  6. Run kinit to get a Kerberos ticket for myWorkload1:

    kinit -k -t /etc/krb5.keytab host/myWorkload1.BigCo.com@MYREALM

  7. Run kinit to get a Kerberos ticket for myWorkload2:

    kinit -k -t /etc/krb5.keytab host/myWorkload2.BigCo.com@MYREALM
Results

The Kerberos-authenticated workloads are created, set in the desired modes, and given a Kerberos ticket.

How to Work with Large Datasets

The --async option is for working with large data sets without waiting for the results. The option works like “batch job.”

The option can be used with any resource. The workflow is as follows:

  1. You issue the desired ilo command with the --async option, which displays a job ID.

  2. You take note of the job ID.

  3. Your session is freed up while the job runs.

  4. The job creates a data file, which you view with datafile --read --job-id jobID.

Goal

Get a report of a large workload data set.

Steps

  1. Issue the --async request for a workload list. Take note of job ID, which is the final word of the href displayed on the Location line.

    [kurt.goedel~]$ ilo workload list --async
Using /home/kurt.goedel/.rvm/gems/ruby-2.2.1 
Location: /orgs/1/jobs/fe8a1c2b-1674-4b83-8967-eb56c4ffa1e3 
202, Accepted

  2. Check to see if the job completed. Use the job ID from the Location output in previous command:

    [sigmund.freud~]$ ilo job read --job-id fe8a1c2b-1674-4b83-8967-eb56c4ffa1e
Using /home/sigmund.freud/.rvm/gems/ruby-2.2.1

  3. Download the resulting data file, specifying the job ID with -uuid jobID:

    [bill.gates ~]$ ilo datafile read --uuid 1e1c1540-8a01-0136-ec14-02f4d6c1190c
Using /home/ bill.gates /.rvm/gems/ruby-2.2.1
+--------------------------------------------------------+---------+------+--
... Many lines not shown
+-----------------------------+----------------------+-----------------------------+----------------------+
| Href                                                   | Deleted | Name | Description | Hostname                
| Service Principal Name | Public Ip             | Distinguished Name | External Data Set | External Data Reference 
| Interfaces | Ignored Interface Names | Service Provider | Data Center 
| Data Center Zone | Os Id | Os Detail | Online | Labels  | Services | Agent  
 | Created At                  | Created By           | Updated At                  | Updated By        
+--------------------------------------------------------+---------+------+-------------+---------------- 
... More lines not shown
---------------------------------------------------------+
| /orgs/1/workloads/50ce441e-75ac-4be8-9201-96169545019c | false   |      |             | 10.14.59.8.netstat
...  
... Many lines not shown 
...
How to Upload Vulnerability Data

This example tutorial shows how to upload vulnerability data to the PCE. For more information, see Upload Vulnerability Data. The source of the vulnerability data in this example comes from Qualys®.

Goal

Upload authoritative vulnerability data for analysis in Illumination.

Steps

  1. Do a non-authoritative upload of vulnerability data for examination:

    ilo upload_vulnerability_report --input-file C:\Users\albert-einstein0.xml --source-scanner qualys --format xml

  2. Examine a single uploaded vulnerability record identified by its vulnerability identifier, qualys-38173. See Vulnerability Identifier for information.

    ilo vulnerability read --xorg-id=1 --reference-id=qualys-38173

  3. Do another non-authoritative upload of vulnerability data.

    ilo upload_vulnerability_report --input-file C:\Users\albert-einstein99.xml --source-scanner qualys --format xml

  4. Do an authoritative upload of vulnerability data, overwriting any previously uploaded records and adding any new vulnerability records.

    ilo upload_vulnerability_report --input-file C:\Users\albert.einstein_FINAL.xml --authoritative --source-scanner qualys --format xml
Results

The authoritative vulnerability data has been uploaded and is ready for use in Illumination.