Deploy Software Agents
Note |
Installer scripts downloaded from LDAP or AD accounts with automatic role mapping fail once you are logged out. To give the installer scripts uninterrupted access to the cluster, enable Use Local Authentication. |
On deployment, the agent is assigned a unique identity by the Secure Workload cluster based on a set of parameters specific to the host where the agent is running. If the host name and the BIOS UUID are a part of the set of parameters, you may encounter the following issues:
-
Registration failure when cloning a virtual machine and retaining the BIOS UUID and host name, and when instant cloning a VDI. The registration failure happens because Secure Workload already has a registered software agent using the same parameters set. You can delete the registered agent using OpenAPI. In some cases, a duplicate BIOS UUID configured during startup is changed by VMware after a certain period of time. Agent registration recovers once the Cisco Secure Workload services are restarted.
-
A new identity is generated for the agent if the host name is changed and the host rebooted. The redundant or the old agent is marked as inactive after a certain period of time. For more information, see Frequently Asked Questions section.
Supported Platforms and Requirements
For information on supported platforms and additional requirements for software agents, see:
-
The release notes for your release, see Release Notes.
-
The agent install wizard in the Secure Workload web portal: In the navigation menu, click Installer tab. Choose an installation method, a platform, and if applicable, an agent type to see supported platform versions.
, then click the -
Support Matrix for additional dependencies.
-
The following sections for details on additional requirements for each platform and agent type.
Installing Linux Agents for Deep Visibility and Enforcement
Requirements and Prerequisites to Install Linux Agents
-
Root privileges to install and execute the services.
-
1-GB storage space for agent and log file.
-
Security exclusions are configured on the security applications that are monitoring the host to prevent these applications from blocking agent installation or agent activity. For more information, see Security Exclusions.
-
A special user, tet-sensor, is created in the host where the agent is installed. If PAM or SELinux is configured on the host, tet-sensor user must be granted appropriate privileges for executing the tet-sensor process and making connections to collectors. If an alternative install directory is provided and SELinux is configured, ensure that execution is allowed for that location.
-
You must be able to use the unzip command, if the agent is installed using the AutoInstall (installer script) method.
Supported Methods to Install Linux Agents
Methods to install a Linux agent for deep visibility and enforcement:
Install Linux Agent using the Agent Image Installer Method
We recommend the automated installer script method for installing Linux agents. Use the image installer method if you have a specific reason for using this manual method..
Prerequisite:
Configure the ACTIVATION_KEY and HTTPS_PROXY in the user.cfg file for SaaS clusters and when you are installing the agent on a non-default tenant of on-premises clusters with multiple tenants. For more information, see (Manual Installations Only) Update the User Configuration File.
To install a Linux agent using the agent image method:
Procedure
Step 1 |
Navigate to Agent Installation Methods:
|
||
Step 2 |
Click Agent Image Installer. |
||
Step 3 |
In the Platform field, enter Linux. |
||
Step 4 |
Enter the required agent type and the version of the agent, and then from the results, download the required version of the agent. |
||
Step 5 |
Copy the RPM package to all the Linux hosts for deployment.
|
||
Step 6 |
Based on your platform, run the RPM commands with root privileges.
|
Install Linux Agent Using the Agent Script Installer Method
We recommend the installer script method to deploy Linux agents for deep visibility and enforcement.
Note |
|
To install a Linux agent using the script installer method:
Procedure
Step 1 |
Navigate to Agent Installation methods:
|
||
Step 2 |
Click Agent Script Installer. |
||
Step 3 |
From the Select Platform drop-down list, choose Linux. To view the supported Linux platforms, click Show Supported Platforms. |
||
Step 4 |
Choose the tenant to install the agents.
|
||
Step 5 |
If you want to assign labels to the workload, choose the label keys and enter label values. When the installed agent reports IP addresses on the host, the installer CMDB labels selected here, along with other uploaded CMDB labels that have been assigned to IPs reported by this host, would be automatically assigned to the new IP address. If there are conflicts between uploaded CMDB labels and installer CMDB labels:
|
||
Step 6 |
If an HTTP proxy is required to communicate with Secure Workload, choose Yes, and then enter a valid proxy URL. |
||
Step 7 |
In the Installer expiration section, select an option:
|
||
Step 8 |
Click Download and save the file to the local disk. |
||
Step 9 |
Copy the installer shell script on Linux hosts and run the following command to grant execute permission to the script:
|
||
Step 10 |
To install the agent, run the following command with root privileges:
|
We recommend running the precheck, as specified in the script usage details.
bash tetration_linux_installer.sh [--pre-check] [--skip-pre-check=<option>] [--no-install] [--logfile=<filename>] [--proxy=<proxy_string>] [--no-proxy] [--help] [--version] [--sensor-version=<version_info>] [--ls] [--file=<filename>] [--save=<filename>] [--new] [--reinstall] [--unpriv-user] [--force-upgrade] [--upgrade-local] [--upgrade-by-uuid=<filename>] [--basedir=<basedir>] [--logbasedir=<logbdir>] [--tmpdir=<tmp_dir>] [--visibility] [--golden-image]
--pre-check: run pre-check only
--skip-pre-check=<option>: skip pre-installation check by given option; Valid options include 'all', 'ipv6' and 'enforcement'; e.g.: '--skip-pre-check=all' will skip all pre-installation checks; All pre-checks will be performed by default
--no-install: will not download and install sensor package onto the system
--logfile=<filename>: write the log to the file specified by <filename>
--proxy=<proxy_string>: set the value of CL_HTTPS_PROXY, the string should be formatted as http://<proxy>:<port>
--no-proxy: bypass system wide proxy; this flag will be ignored if --proxy flag was provided
--help: print this usage
--version: print current script's version
--sensor-version=<version_info>: select sensor's version; e.g.: '--sensor-version=3.4.1.0'; will download the latest version by default if this flag was not provided
--ls: list all available sensor versions for your system (will not list pre-3.1 packages); will not download any package
--file=<filename>: provide local zip file to install sensor instead of downloading it from cluster
--save=<filename>: download and save zip file as <filename>
--new: remove any previous installed sensor; previous sensor identity has to be removed from cluster in order for the new registration to succeed
--reinstall: reinstall sensor and retain the same identity with cluster; this flag has higher priority than --new
--unpriv-user=<username>: use <username> for unpriv processes instead of tet-sensor
--force-upgrade: force sensor upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --force-upgrade'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-local: trigger local sensor upgrade to version given by --sensor-version flag: e.g.: '--sensor-version=3.4.1.0 --upgrade-local'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-by-uuid=<filename>: trigger sensor whose uuid is listed in <filename> upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --upgrade-by-uuid=/usr/local/tet/sensor_id'; apply the latest version by default if --sensor-version flag was not provided
--basedir=<base_dir>: instead of using /usr/local use <base_dir> to install agent. The full path will be <base_dir>/tetration
--logbasedir=<log_base_dir>: instead of logging to /usr/local/tet/log use <log_base_dir>. The full path will be <log_base_dir>/tetration
--tmpdir=<tmp_dir>: instead of using /tmp use <tmp_dir> as temp directory
--visibility: install deep visibility agent only; --reinstall would overwrite this flag if previous installed agent type was enforcer
--golden-image: install Cisco Secure Workload Agent but do not start the Cisco Secure Workload Services; use to install Cisco Secure Workload Agent on Golden Images in VDI environment or Template VM. On VDI/VM instance created from golden image with different host name, Cisco Secure Workload Services will work normally
Note |
|
Verify Linux Agent Installation
Procedure
Run the command sudo rpm -q tet-sensor
Sample output: The specific output may differ depending on the platform and architecture. |
Installing Windows Agents for Deep Visibility and Enforcement
Requirements and Prerequisites for Installing Windows Agent
-
See the Supported Platforms and Requirements section.
-
Administrator privileges are required for installation and service execution.
-
Npcap must be installed on workloads running Windows 2008 R2 or when the installed agent version is earlier than version 3.8. If the Npcap driver is not already installed, the recommended Npcap version is installed in the background by the agent after the service starts. For more information, see the Npcap version information.
-
One GB storage space for agent and log files.
-
Enable the Windows services required for agent installation. Some of the Windows services could have been disabled if your Windows hosts have been security hardened, or have deviated from the default configurations. For more information, see the Required Windows Services section.
-
Security exclusions configured on security applications that are monitoring the host and that could block agent installation or agent activity. For more information, see Security Exclusions.
Supported Methods to Install Windows Agents
There are two methods to install Windows agents for deep visibility and enforcement.
-
Install Windows Agent using the Agent Script Installer Method
-
Install Windows Agent using the Agent Image Installer Method
You can also install using a golden image. For more information, see Deploying Agents on a VDI Instance or VM Template (Windows).
Install Windows Agent using the Agent Script Installer Method
We recommend the script installer method to deploy Windows agents for deep visibility and enforcement.
Note |
|
To install a Windows agent using the script installer method:
Procedure
Step 1 |
Navigate to Agent Installation Methods:
|
||
Step 2 |
Click Agent Script Installer. |
||
Step 3 |
From the Select Platform drop-down menu, choose Windows. To view the supported Windows platforms, click Show Supported Platforms. |
||
Step 4 |
Choose the tenant to install the agents.
|
||
Step 5 |
If you want to assign labels to the workload, choose the label keys and enter label values. When the installed agent reports IP addresses on the host, the installer CMDB labels selected here, along with other uploaded CMDB labels that have been assigned to IPs reported by this host, would be assigned to the new IP address. If there are conflicts between uploaded CMDB labels and installer CMDB labels:
|
||
Step 6 |
If HTTP proxy is required to communicate with Secure Workload, choose Yes, and then enter a valid proxy URL. |
||
Step 7 |
Under the Installer expiration section, select one from the available options:
|
||
Step 8 |
Click Download and save the file to the local disk. |
||
Step 9 |
Copy the installer PowerShell script to all the Windows hosts for deployment and run the script with administrative privileges.
|
# powershell -ExecutionPolicy Bypass -File tetration_windows_installer.ps1 [-preCheck] [-skipPreCheck <Option>] [-noInstall] [-logFile <FileName>] [-proxy <ProxyString>] [-noProxy] [-help] [-version] [-sensorVersion <VersionInfo>] [-ls] [-file <FileName>] [-save <FileName>] [-new] [-reinstall] [
-npcap] [-forceUpgrade] [-upgradeLocal] [-upgradeByUUID <FileName>] [-visibility] [-goldenImage] [-installFolder <Installation Path>]
-preCheck: run pre-check only
-skipPreCheck <Option>: skip pre-installation check by given option; Valid options include 'all', 'ipv6' and 'enforcement'; e.g.: '-skipPreCheck all' will skip all pre-installation checks; All pre-checks will be performed by default
-noInstall: will not download and install sensor package onto the system
-logFile <FileName>: write the log to the file specified by <FileName>
-proxy <ProxyString>: set the value of HTTPS_PROXY, the string should be formatted as http://<proxy>:<port>
-noProxy: bypass system wide proxy; this flag will be ignored if -proxy flag was provided
-help: print this usage
-version: print current script's version
-sensorVersion <VersionInfo>: select sensor's version; e.g.: '-sensorVersion 3.4.1.0.win64'; will download the latest version by default if this flag was not provided
-ls: list all available sensor versions for your system (will not list pre-3.1 packages); will not download any package
-file <FileName>: provide local zip file to install sensor instead of downloading it from cluster
-save <FileName>: downloaded and save zip file as <FileName>
-new: remove any previous installed sensor; previous sensor identity has to be removed from cluster in order for the new registration to succeed
-reinstall: reinstall sensor and retain the same identity with cluster; this flag has higher priority than -new
-npcap: overwrite existing npcap
-forceUpgrade: force sensor upgrade to version given by -sensorVersion flag; e.g.: '-sensorVersion 3.4.1.0.win64 -forceUpgrade'; apply the latest version by default if -sensorVersion flag was not provided
-upgradeLocal: trigger local sensor upgrade to version given by -sensorVersion flag; e.g.: '-sensorVersion 3.4.1.0.win64 -upgradeLocal'; apply the latest version by default if -sensorVersion flag was not provided
-upgradeByUUID <FileName>: trigger sensor whose uuid is listed in <FileName> upgrade to version given by -sensorVersion flag; e.g.: '-sensorVersion 3.4.1.0.win64 -upgradeByUUID "C:\\Program Files\\Cisco Tetration\\sensor_id"'; apply the latest version by default if -sensorVersion flag was not provided
-visibility: install deep visibility agent only; -reinstall would overwrite this flag if previous installed agent type was enforcer
-goldenImage: install Cisco Secure Workload Agent but do not start the Cisco Secure Workload Services; use to install Cisco Secure Workload Agent on Golden Images in VDI environment or Template VM. On VDI/VM instance created from golden image with different host name, Cisco Secure Workload Services will work normally
-installFolder: install Cisco Secure Workload Agent in a custom folder specified by -installFolder e.g.: '-installFolder "c:\\custom sensor path"'; default path is "C:\Program Files\Cisco Tetration"
Install Windows Agent using the Agent Image Installer Method
We recommend the automated installer script method for installing Windows agents. Use the image installer method if you have a specific reason for using this manual method.
Note |
Do not manually deploy an older MSI agent version when an existing agent is already running on the host. |
Site-related files that are in the package:
-
ca.cert—Mandatory—CA certificate for sensor communications.
-
enforcer.cfg—Mandatory only when installing enforcement sensor—Contains configuration of enforcement endpoints.
-
sensor_config—Mandatory—Configuration for deep visibility sensor.
-
sensor_type—Type of the sensor (enforcement or deep visibility).
-
site.cfg—Mandatory—Global site endpoint configuration.
-
user.cfg—Mandatory for SaaS—Sensor activation key and proxy configuration.
Prerequisite:
Configure the ACTIVATION_KEY and HTTPS_PROXY in the user.cfg file for SaaS clusters and when you are installing the agent on a non-default tenant of on-premises clusters with multiple tenants. For more information, see (Manual Installations Only) Update the User Configuration File.
To install a Windows agent using the agent image method:
Procedure
Step 1 |
Navigate to Agent Installation Methods:
|
||||||||||||||||||
Step 2 |
Click Agent Image Installer. |
||||||||||||||||||
Step 3 |
In the Platform field, enter Windows. |
||||||||||||||||||
Step 4 |
Enter the required agent type and the version of the agent, and then from the results, download the required version of the agent. |
||||||||||||||||||
Step 5 |
Copy the tet-win-sensor<version>.win64-<clustername>.zip file to all the Windows hosts for deployment. |
||||||||||||||||||
Step 6 |
Ensure that you have administrative privileges and extract the ZIP file. |
||||||||||||||||||
Step 7 |
In the extracted folder, run the following command to install the agent: Additionally, the following options are available for MSI installer.
|
Note |
|
Verify Windows Agent Installation
Procedure
Step 1 |
Ensure that the folder |
Step 2 |
Ensure that the service—TetSensor
, for deep visibility and enforcement, exists and is in the running state. Run command Run the command Check if the status is Running Run the command Check if the DISPLAY-NAME is Cisco Secure Workload Deep Visibility OR Run the command services.msc Find the name Cisco Secure Workload Deep Visibility Check if the status is Running |
Verify Windows Agent in the Configured Service User Context
-
Ensure that the service TetSensor (for deep visibility) and TetEnforcer (for enforcement) running in the config- ured service user context. TetSensor and TetEnforcer run in the same service user context.
Run the command
cmd.exe
with Admin privilegesRun the command
sc qc tetsensor
Check SERVICE_START_NAME <configured service user>
Run the command
sc qc tetenforcer
Check SERVICE_START_NAME <configured service user>
OR
Run the command
services.msc
Find the name Cisco Secure Workload Deep Visibility
Check Log On As for the <configured service user>
Find the name Cisco Secure Workload Enforcement
Check Log On As for the <configured service user>
OR
Run the command
tasklist /v | find /i “tet”
Run the command
tasklist /v | find /i “cswengine”
Check the user context for the running processes (5th column)
Modify Service Account
After installing Windows Agents, use one of the following methods to modify the existing Deep Visibility and Enforcement services.
-
Use services.msc.
-
Use any third party application to configure the services.
-
Use the following commands:
-
Run cmd as an administrator.
-
Modify the services using the service account name by running the following commands:
-
sc config tetsensor obj= <service user name> password= <password>
-
sc config tetenforcer obj= <service user name> password= <password>
-
-
Verify service configurations by running the following commands:
-
sc qc tetsensor
-
sc qc tetenforcer
-
-
Restart the tetsensor and tetenforcer services by running the following commands:
-
sc stop tetsensor / tetenforcer
-
sc start tetsensor / tetenforcer
-
-
Deploying Agents on a VDI Instance or VM Template (Windows)
By default, agent services start automatically after agents are installed. When installing on a golden image, you must use installer flags to prevent these services from starting. When instances are cloned from the golden image, agent services, as expected, start automatically.
Agent will not install Npcap on golden VMs, but will be automatically installed if needed on VM instances cloned from a golden image. For more information, see Windows Agent Installer and Npcap.
Install the agent on a golden image in a VDI environment or VM template
Procedure
Step 1 |
Install the agent on a golden image in a VDI environment or VM template using an MSI installer or PowerShell installer script: Use MSI installer with nostart=yes
OR Use PowerShell installer with the -goldenImage flag.
|
Step 2 |
Ensure that the folder |
Step 3 |
Ensure that the service TetSensor (for deep visibility) exists and is stopped: Run the command Run the command Check if the STATE is Stopped. |
Step 4 |
Ensure that the service TetEnforcer (for enforcement) exists and is stopped: Run the command sc query tetenforcer. Check if the STATE is Stopped . |
Step 5 |
The VM template is now configured. |
Step 6 |
Shut down the VM template. |
Create a new VDI instance VM
Procedure
Step 1 |
Create a new VDI instance VM by cloning the VM template. |
||
Step 2 |
Reboot the VDI instance VM. |
||
Step 3 |
After rebooting the VDI instance VM, ensure that the services – TetSensor (for deep visibility) and TetEnforcer (for enforcement) – are running in the configured service context. See Verify the Agent is Installed. |
||
Step 4 |
On the VDI instance VM, ensure that the NPCAP driver is installed and running: Run the command Run the command Check if STATE is Running |
||
Step 5 |
On the VDI instance VM, ensure that the agent is registered using a valid sensor_id:
|
Windows Agent Installer and Npcap—For Windows 2008 R2
-
For supported Npcap versions, see the Support Matrix at https://www.cisco.com/go/secure-workload/requirements/agents.
-
Installation:
If Npcap is not installed, the agent installs the supported version ten seconds after the service starts. If User has Npcap installed but the version is older than the supported version, Npcap is not be upgraded. Manually upgrade or uninstall Npcap, run the agent installer with the option overwritenpcap=yes, or run installer script with -npcap to get the supported Npcap version. If Npcap driver is in use by any application, the agent upgrades Npcap at a later time.
-
Upgrade:
If Npcap is installed by Windows Agent and the version is older than the supported version, Npcap is upgraded to the supported version ten seconds after the service starts. If Npcap driver is in use by any application, the agent upgrades Npcap at a later time. If Npcap is not installed by Windows Agent, Npcap is not upgraded.
-
Uninstall:
If Npcap is installed by the Windows Agent, the agent uninstalls Npcap. If Npcap is installed by the user, but upgraded by the agent installer with overwritenpcap=yes, Npcap is not uninstalled. If Npcap driver is in use by any application, the agent does not uninstall Npcap.
Windows Agent Flow Captures: For All Windows OS Excluding Windows Server 2008 R2
From the latest version of Windows, the agent uses ndiscap.sys (Microsoft in-built) driver and Events Tracing using Windows (ETW) framework to capture the network flows.
During the upgrade to the latest version:
-
The agent switches to ndiscap.sys from npcap.sys.
-
The agent installer uninstalls Npcap if:
-
Npcap is installed by the agent.
-
Npcap is not in use.
-
OS version is not Windows Server 2008 R2.
-
After the agent services are started, the agent creates ETW sessions, CSW_MonNet, and CSW_MonDns (for DNS data), and initiates the capture of network flows.
Note |
|
Installing AIX Agents for Deep Visibility and Enforcement
Note |
Process tree, Package (CVE), and Forensic Event reporting features are not available on AIX. Additionally, some aspects of those features may not be available on specific minor releases of otherwise supported platforms due to OS limitations. |
Requirements and Prerequisites for Installing AIX Agents
-
Additional requirements for deep visibility:
-
Root privileges to install and execute the services.
-
Storage requirement for agent and log files: 500 MB.
-
Security exclusions configured on any security applications that are monitoring the host. These exclusions are to prevent other security applications from blocking agent installation or agent activity. For more information, see Security Exclusions.
-
AIX supports flow capture of only 20 network devices (6 network devices if version is AIX 7.1 TL3 SP4 or earlier). The deep visibility agent captures from a maximum of 16 network devices, leaving the other 4 capture sessions available for exclusive generic system usage (For example, tcpdump).
-
The deep visibilty agent does the following to ensure flow capture of 20 network devices:
-
The agent creates 16 bpf device nodes under the agents directory (/opt/cisco/tetration/chroot/dev/bpf0 - /opt/cisco/tetration/chroot/dev/bpf15)
-
tcpdump and other system tools using bpf will scan through the system device nodes (/dev/bpf0-/dev/bpf19) until they find an unused node (!EBUSY)
-
The bpf nodes created by the agent and the system bpf nodes share the same major/minor, with each major or minor being opened only by one instance (either tcpdump or agent).
-
The agent does not access the system device nodes nor does it create them as the tcpdump does (tcpdump-D creates /dev/bpf0. . . /dev/bpf19 if they do not exist).
-
-
Running iptrace on the system prevents, in certain scenarios, flow capture from tcpdump and the deep visibilty agent. This is a known design issue and needs to be checked with IBM.
-
To check if this scenario exists, before installing the agent, run tcpdump. If error message is tcpdump: BIOCSETIF: en0: File exists the iptrace is blocking flow capture. Stop iptrace to resolve the issue.
-
-
All deep visibility functions are not supported in AIX. Package and process accounting are among the ones not supported.
-
-
Additional requirements for policy enforcement:
-
If IP Security Filter is enabled (that is, smitty IPsec4), agent installation fails in pre-check. We recommend you to disable IP Security Filter before installing the agent.
-
If IP Security is enabled when the Secure Workload enforcer agent is running, an error is reported and the enforcer agent stops enforcing. Contact support to safely disable the IP Security filter when the enforcer agent is running.
-
Install AIX Agent using the Agent Script Installer Method
Deep visibility and enforcement AIX agents can only be installed using the Agent Script Installation method.
Note |
|
To install an AIX agent:
Procedure
Step 1 |
Navigate to Agent Installation Methods:
|
||
Step 2 |
Click Agent Script Installer. |
||
Step 3 |
From the Select Platform drop-down menu, choose AIX. To view the supported AIX platforms, click Show Supported Platforms. |
||
Step 4 |
Choose the tenant to install the agents.
|
||
Step 5 |
If you want to assign labels to the workload, choose the label keys and enter label values. When the installed agent reports IP addresses on the host, the installer CMDB labels selected here, along with other uploaded CMDB labels that have been assigned to IPs reported by this host, would be automatically assigned to the new IP address. If there are conflicts between uploaded CMDB labels and installer CMDB labels:
|
||
Step 6 |
If HTTP proxy is required to communicate with Secure Workload, choose Yes, and then enter a valid proxy URL. |
||
Step 7 |
Under the Installer expiration section, select one from the available options:
|
||
Step 8 |
Click Download and save the file to the local disk. |
||
Step 9 |
Copy the installer shell script to all the AIX hosts for deployment. |
||
Step 10 |
To grant execute permission to the script, run the command:
|
||
Step 11 |
To install the agent, run the following command with root privileges:
|
We recommend running the pre-check, as specified in the script usage details.
AIX installer script usage details:
ksh tetration_installer_default_enforcer_aix.sh [--pre-check] [--pre-check-user] [--skip-pre-check=<option>] [--no-install] [--logfile=<filename>] [--proxy=<proxy_string>] [--no-proxy] [--help] [--version] [--sensor-version=<version_info>] [--ls] [--file=<filename>] [--osversion=<osversion>] [--save=<filename>] [--new] [--reinstall] [--unpriv-user] [--libs=<libs.zip|tar.Z>] [--force-upgrade] [--upgrade-local] [--upgrade-by-uuid=<filename>] [--logbasedir=<logbdir>] [--tmpdir=<tmp_dir>] [--visibility] [--golden-image]
--pre-check: run pre-check only
--pre-check-user: provide alternative to nobody user for pre-check su support
--skip-pre-check=<option>: skip pre-installation check by given option; Valid options include 'all', 'ipv6' and 'enforcement'; e.g.: '--skip-pre-check=all' will skip all pre-installation checks; All pre-checks will be performed by default
--no-install: will not download and install sensor package onto the system
--logfile=<filename>: write the log to the file specified by <filename>
--proxy=<proxy_string>: set the value of HTTPS_PROXY, the string should be formatted as http://<proxy>:<port>
--no-proxy: bypass system wide proxy; this flag will be ignored if --proxy flag was provided
--help: print this usage
--version: print current script's version
--sensor-version=<version_info>: select sensor's version; e.g.: '--sensor-version=3.4.1.0'; will download the latest version by default if this flag was not provided
--ls: list all available sensor versions for your system (will not list pre-3.3 packages); will not download any package
--file=<filename>: provide local zip file to install sensor instead of downloading it from cluster
--osversion=<osversion>: specify osversion for --save flag;
--save=<filename>: download and save zip file as <filename>; will download package for osversion given by --osversion flag; e.g.: '--save=myimage.aix72.tar.Z --osversion=7.2'
--new: remove any previous installed sensor; previous sensor identity has to be removed from cluster in order for the new registration to succeed
--reinstall: reinstall sensor and retain the same identity with cluster; this flag has higher priority than --new
--unpriv-user=<username>: use <username> for unpriv processes instead of tet-snsr
--libs=<libs.zip|tar.Z>: install provided libs to be used by agents
--force-upgrade: force sensor upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --force-upgrade'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-local: trigger local sensor upgrade to version given by --sensor-version flag: e.g.: '--sensor-version=3.4.1.0 --upgrade-local'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-by-uuid=<filename>: trigger sensor whose uuid is listed in <filename> upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --upgrade-by-uuid=/usr/local/tet/sensor_id'; apply the latest version by default if --sensor-version flag was not provided
--logbasedir=<log_base_dir>: instead of logging to /opt/cisco/tetration/log use <log_base_dir>. The full path will be <log_base_dir>/tetration
--tmpdir=<tmp_dir>: instead of using /tmp use <tmp_dir> as temp directory
--visibility: install deep visibility agent only; --reinstall would overwrite this flag if previous installed agent type was enforcer
--golden-image: install Cisco Secure Workload Agent but do not start the Cisco Secure Workload Services; use to install Cisco Secure Workload Agent on Golden Images in VDI environment or Template VM. On VDI/VM instance created from golden image with different host name, Cisco Secure Workload Services will work normally
Verify AIX Agent Installation
Procedure
Run command
Subsystem Group PID Status tet-sensor 1234567 active
Subsystem Group PID Status tet-enforcer 7654321 active |
Installing Kubernetes or OpenShift Agents for Deep Visibility and Enforcement
Requirements and Prerequisites
Operating system support information is available at Agent OS support matrix.
Requirements
-
The install script requires Kubernetes or OpenShift administrator credentials to start privileged agent pods on the cluster nodes.
-
Secure Workload entities are created in the tetration namespace.
-
The node or pod security policies must permit privileged mode pods.
-
busybox:1.33 images must either be preinstalled or be downloadable from Docker Hub.
-
For containerd run time, if the config_path is not set, modify your config.toml (default location: /etc/containerd/config.toml) as follows: ``` [plugins."io.containerd.grpc.v1.cri".registry] config_path = "/etc/containerd/certs.d" ```
Restart the containerd daemon.
-
To run on Kubernetes or OpenShift control plane nodes, the –toleration flag can be used to pass in a toleration for the Secure Workload pods. The toleration that is usually passed is the NoSchedule toleration that normally prevents pods from running on control plane nodes.
-
For Windows worker nodes:
-
Supported Windows worker node container runtime: ContainerD.
-
ContainerD config: Configure the following containerd change. ``` [plugins."io.containerd.grpc.v1.cri".registry] config_path = "/etc/containerd/certs.d" ```
Remove configurations under registry.mirrors. The default configuration file location is C:\Program Files\containerd\config.toml.
Restart the containerd daemon after the configuration changes.
-
The image mcr.microsoft.com/oss/kubernetes/windows-host-process-containers-base-image:v1.0.0 must either be preinstallated or downloadable on the Windows worker node.
-
The existing Kubernetes agent which is upgrading to the newer version includes the Windows DaemonSet agent automatically. However, the previous script does not uninstall the Windows DaemonSet agent. Download the latest installer script to uninstall the Windows DaemonSet agent.
-
Supported on:
-
Microsoft Windows Server 2022
-
Windows Server 2019
-
Kubernetes 1.27 and later
-
-
Requirements for Policy Enforcement
IPVS-based kube-proxy mode is not supported for OpenShift.
These agents should be configured with the Preserve Rules option that is enabled. For more information, see Creating an Agent Config Profile.
For enforcement to function properly, any installed CNI plug-in must:
-
Provide flat address space (IP network) between all nodes and pods. Network plug-ins that masquerade the source pod IP for intracluster communication are not supported.
-
Not interfere with Linux iptables rules or marks that are used by the Secure Workload Enforcement Agent (mark bits 21 and 20 are used to allow and deny traffic for NodePort services)
The following CNI plug-ins are tested for the above requirements:
-
Calico (3.13) with the following Felix configurations: (ChainInsertMode: Append, Ipta- blesRefreshInterval: 0) or (ChainInsertMode: Insert, IptablesFilterAllowAction: Return, IptablesMangleAllowAction: Return, IptablesRefreshInterval: 0). All other options use their default values.
For more information on setting these options, see the Felix configuration reference.
Install Kubernetes or OpenShift Agent using the Agent Script Installer Method
Note |
The agent script installer method automatically installs agents on nodes included later. |
Procedure
Step 1 |
Navigate to the Agent Installation Methods:
|
||
Step 2 |
Click Agent Script Installer. |
||
Step 3 |
From the Select Platform drop-down menu, choose Kubernetes. To view the supported Kubernetes or OpenShift platforms, click Show Supported Platforms. |
||
Step 4 |
Choose the tenant to install the agents.
|
||
Step 5 |
If HTTP proxy is required to communicate with Secure Workload, choose Yes, and then enter a valid proxy URL. |
||
Step 6 |
Click Download and save the file to the local disk. |
||
Step 7 |
Run the installer script on a Linux machine which has access to the Kubernetes API server and a kubectl configuration file with administrative privileges as the default context/cluster/user. The installer attempts to read the file from its default location (~/.kube/config). However, you can explicitly specify the location of the config file using the --kubeconfig command. |
The installation script provides instructions for verifying the Secure Workload Agent Daemonset and the Pods that were installed.
Note |
The HTTP Proxy configured on the agent installer page prior to download only controls how Secure Workload agents connect to the Secure Workload cluster. This setting does not affect how Docker images are fetched by Kubernetes or OpenShift nodes, because the container runtime on those nodes uses its own proxy configuration. If the Docker images are not fetched from the Secure Workload cluster, debug the image pulling process of the container and add a suitable HTTP proxy. |
Installing Solaris Agents for Deep Visibility and Enforcement
Requirements and Prerequisites for Installing Solaris Agents
-
Root privileges to install and execute the services.
-
One GB storage space for agent and log files.
-
Configuration of security exclusions on security applications that are monitoring the host, to prevent other security applications from blocking of agent installation or agent activity. For more information, see Security Exclusions.
Install Solaris Agent using the Agent Script Installer Method
The installed Solaris agent supports both deep visibility and process or package visibility.
Procedure
Step 1 |
Navigate to Agent Installation Methods:
|
||
Step 2 |
Click Agent Script Installer. |
||
Step 3 |
From the Select Platform drop-down menu, choose Solaris. To view the supported Solaris platforms, click Show Supported Platforms. |
||
Step 4 |
Choose the tenant to install the agents.
|
||
Step 5 |
If you want to assign labels to the workload, choose the label keys and enter label values. When the installed agent reports IP addresses on the host, the installer CMDB labels selected here, along with other uploaded CMDB labels that have been assigned to IPs reported by this host, would be assigned automatically to the new IP address. If there are conflicts between uploaded CMDB labels and installer CMDB labels:
|
||
Step 6 |
If HTTP proxy is required to communicate with Secure Workload, choose Yes, and then enter a valid proxy URL. |
||
Step 7 |
Under the Installer expiration section, select one from the available options:
|
||
Step 8 |
Click Download and save the file to the local disk. |
||
Step 9 |
Copy the installer shell script on Solaris hosts and run the following command to grant execute permission to the script:
|
||
Step 10 |
To install the agent, run the following command with root privileges:
|
We recommend running the precheck, as specified in the script usage details.
Solaris installer script usage details:
tetration_installer_default_sensor_solaris.sh [--pre-check] [--skip-pre-check=<option>] [--no-install] [--logfile=<filename>] [--proxy=<proxy_string>] [--no-proxy] [--help] [--version] [--sensor-version=<version_info>] [--ls] [--file=<filename>] [--save=<filename>] [--new] [--reinstall] [--unpriv-user] [--force-upgrade] [--upgrade-local] [--upgrade-by-uuid=<filename>] [--basedir=<basedir>] [--logbasedir=<logbdir>] [--tmpdir=<tmp_dir>] [--visibility] [--golden-image]
--pre-check: run pre-check only
--skip-pre-check=<option>: skip pre-installation check by given option; Valid options include 'all', 'ipv6' and 'enforcement'; e.g.: '--skip-pre-check=all' will skip all pre-installation checks; All pre-checks will be performed by default
--no-install: will not download and install sensor package onto the system
--logfile=<filename>: write the log to the file specified by <filename>
--proxy=<proxy_string>: set the value of CL_HTTPS_PROXY, the string should be formatted as http://<proxy>:<port>
--no-proxy: bypass system wide proxy; this flag will be ignored if --proxy flag was provided
--help: print this usage
--version: print current script's version
--sensor-version=<version_info>: select sensor's version; e.g.: '--sensor-version=3.4.1.0'; will download the latest version by default if this flag was not provided
--ls: list all available sensor versions for your system (will not list pre-3.1 packages); will not download any package
--file=<filename>: provide local zip file to install sensor instead of downloading it from cluster
--save=<filename>: download and save zip file as <filename>
--new: remove any previous installed sensor; previous sensor identity has to be removed from cluster in order for the new registration to succeed
--reinstall: reinstall sensor and retain the same identity with cluster; this flag has higher priority than --new
--unpriv-user=<username>: use <username> for unpriv processes instead of nobody
--force-upgrade: force sensor upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --force-upgrade'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-local: trigger local sensor upgrade to version given by --sensor-version flag: e.g.: '--sensor-version=3.4.1.0 --upgrade-local'; apply the latest version by default if --sensor-version flag was not provided
--upgrade-by-uuid=<filename>: trigger sensor whose uuid is listed in <filename> upgrade to version given by --sensor-version flag; e.g.: '--sensor-version=3.4.1.0 --upgrade-by-uuid=/usr/local/tet/sensor_id'; apply the latest version by default if --sensor-version flag was not provided
--logbasedir=<log_base_dir>: instead of logging to /opt/cisco/secure-workload/log use <log_base_dir>. The full path will be <log_base_dir>/secure-workload
--tmpdir=<tmp_dir>: instead of using /tmp use <tmp_dir> as temp directory
--visibility: install deep visibility agent only; --reinstall would overwrite this flag if previous installed agent type was enforcer
--golden-image: install Cisco Secure Workload Agent but do not start the Cisco Secure Workload Services; use to install Cisco Secure Workload Agent on Golden Images in VDI environment or Template VM. On VDI/VM instance created from golden image with different host name, Cisco Secure Workload Services will work normally
Verify Solaris Agent Installation
Procedure
Step 1 |
Run the command: |
||||||||
Step 2 |
A single entry as output confirms that a Solaris agent is installed on the host.
|
(Manual Installations Only) Update the User Configuration File
The following procedure is required only for installations involving all of the following:
-
Secure Workload SaaS, or on-premises clusters with multiple tenants (on-premises clusters that use only the default tenant do NOT need this procedure)
-
Manual installation
-
Linux or Windows platform
Agents require an activation key to register to the Secure Workload cluster. they require a cluster activation key. Additionally, they might need an HTTPS proxy to reach the cluster.
Note |
In Windows Environment, you do not need to manually configure user.cfg, if activationkey and proxy options are used during manual installation. |
Before installation, configure the required variables in the user configuration file:
Procedure
Step 1 |
To retrieve your activation key, navigate to , click the Installer tab, click Manual Install using classic packaged installers, then click Agent Activation Key. |
Step 2 |
Open the |
Step 3 |
Add the activation key to the ACTIVATION_KEY variable. Example: |
Step 4 |
If the agent requires an HTTPS proxy, add the http protocol proxy server and port using the HTTPS_PROXY variable. Example: |
Other Agent-Like Tools
AnyConnect Agents
No Secure Wrokload agent is required for platforms supported by Cisco AnyConnect Secure Mobility agent with Network Visibility Module (NVM). AnyConnect connector registers these agents and exports flow observations, inventories, and labels to Secure Workload. For more information, see AnyConnect Connector.
For Windows, Mac, or Linux platforms, see Cisco AnyConnect Secure Mobility Client Data Sheet.
ISE Agents
A Secure Workload agent on the endpoint is not required for endpoints registered with Cisco Identity Service Engine (ISE). ISE connector collects metadata about endpoints from ISE through pxGrid service on ISE appliance. It registers the endpoints as ISE agents on Secure Workload and pushes labels for the inventories on these endpoints. For more information, see ISE Connector.
SPAN Agents
SPAN agents work with the ERSPAN connector. For more information, see ERSPAN Connector.
Third-Party and Additional Cisco Products
-
For integrations using external orchestrators configured in Secure Workload,
-
For integrations using connectors configured in Secure Workload.
See What are Connectors.
Connectivity Information
In general, when the agent is installed on the workload, it makes several network connections to the back-end services hosted on the Secure Workload cluster. The number of connections will vary depending on the agent type and its functions.
The following table captures various permanent connections that are made by various agent types.
Agent type |
Config server |
Collectors |
Enforcement backend |
---|---|---|---|
visibility (on-premises) |
CFG-SERVER-IP:443 |
COLLECTOR-IP:5640 |
N/A |
visibility (SaaS) |
CFG-SERVER-IP:443 |
COLLECTOR-IP:443 |
N/A |
enforcement (on-premises) |
CFG-SERVER-IP:443 |
COLLECTOR-IP:5640 |
ENFORCER-IP:5660 |
enforcement (SaaS) |
CFG-SERVER-IP:443 |
COLLECTOR-IP:443 |
ENFORCER-IP:443 |
docker images |
CFG-SERVER-IP:443 |
N/A |
N/A |
Legends:
-
CFG-SERVER-IP is the IP address of the config server.
-
COLLECTOR-IP is the IP address of the collector. Deep visibility and enforcement agents connect to all available collectors.
-
ENFORCER-IP is the IP address of the enforcement endpoint. The enforcement agent connects to only one of the available endpoints.
-
For Kubernetes/Openshift agent deployments, the installation script does not contain the agent software - Docker images containing the agent software are pulled from the Secure Workload cluster by every Kubernetes/Openshift node. These connections are established by the container run time image fetch component and directed at CFG-SERVER-IP:443.
Navigate to Platform > Cluster Configuration to know the config server IP and collector IP.
-
Sensor VIP is for the config server IP: The IP address that has been set up for the config server in this cluster.
-
External IPs are for collectors IPs and enforcer: If this is populated, when assigning external cluster IP addresses, the selection process is restricted to only IP addresses defined in this list, that are part of the external network.
Note |
|
Connections to the cluster might be denied if the workload is behind a firewall, or if the host firewall service is enabled. In such cases, administrators must create appropriate firewall policies to allow the connections.