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 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 |
|
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.
|
Verify Linux Agent Installation
Procedure
Run 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
-
For more information, see the Supported Platforms and Requirements.
-
Administrator privileges are required for install and service execution.
-
Npcap must be installed on workloads running Windows 2008 R2 or when the installed agent version is prior to version 3.8. If the Npcap driver is not already installed, the recommended Npcap version will be installed silently by the agent after the service starts.
For more information, see the Npcap version information.
-
Storage requirement for agent and log files: 1 GB.
-
Required Windows services: If your Windows hosts have been security that is hardened or have deviated from the default configuration as shipped from Microsoft, you may have some Windows services disabled that are required for successful agent installation.
For more information, see the Required Windows Services section.
-
Prevent other security applications from blocking agent installation or agent activity by configuring security exclusions on the security applications that are monitoring the host. See
For more information, see the Security Exclusions section.
Supported Methods to Install Windows Agents
There are two methods to install an agent on Windows platforms for deep visibility or 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. See Deploying Agents on a VDI Instance or VM Template (Windows).
Install Windows Agent using the Agent Script Installer Method
The installer script is the recommended method to deploy agents on Windows platforms for deep visibility or enforcement.
Note |
|
To install a Windows agent using the script installer method:
Procedure
Step 1 |
To navigate to the 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 |
(Optional) 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 automatically. 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 local disk. |
||
Step 9 |
Copy the installer PowerShell script to all the Windows hosts for deployment and run the script with administrative privileges.
|
# powershell -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 that the installer script method (automated) is used to install the Windows agents, unless you have a specific reason to install the agent manually using the Agent Image method.
Note |
Do not manually deploy an older MSI agent version when an existing agent is already running on the host. |
Site-related files 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:
For SaaS clusters and when you are not installing under the default tenant on on-premises clusters with multiple tenants, you must configure the ACTIVATION_KEY and HTTPS_PROXY in the user.cfg file. 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 |
To navigate to the 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 |
With administrative privileges, 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 |
Verify that the folder |
Step 2 |
Verify that the service—TetSensor, for deep visibility, exists and is in the running state. Run command Run command Check state Running Run command Check DISPLAY-NAME Cisco Secure Workload Deep Visibility OR Run command services.msc Find name Cisco Secure Workload Deep Visibility Check status Running |
Step 3 |
Verify that the service—TetEnforcer, for enforcement, exist and is in the running state. Run command Run command Check state Running Run command Check DISPLAY-NAME Cisco Secure Workload Enforcement OR Run command Find name Cisco Secure Workload Enforcement Check status Running |
Verify Windows Agent in the Configured Service User Context
-
Verify 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 command
cmd.exe
with Admin privilegesRun command
sc qc tetsensor
Check SERVICE_START_NAME <configured service user>
Run command
sc qc tetenforcer
Check SERVICE_START_NAME <configured service user>
OR
Run command
services.msc
Find name Cisco Secure Workload Deep Visibility
Check Log On As for the <configured service user>
Find name Cisco Secure Workload Enforcement
Check Log On As for the <configured service user>
OR
Run command
tasklist /v | find /i “tet”
Check the user context for the running processes (5th column)
Modify Service Account
To modify the 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 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 will start automatically as expected.
Similarly, NPCAP is normally installed automatically after agent installation if it is not already present. NPCAP is not automatically installed on golden images, 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: Using MSI installer with nostart=yes
OR Using PowerShell installer with the -goldenImage flag.
|
Step 2 |
Verify that the folder |
Step 3 |
Verify that the service TetSensor (for deep visibility) exists and is stopped: Run command Run command Check STATE Stopped |
Step 4 |
Verify that the service TetEnforcer (for enforcement) exists and is stopped: Run command sc query tetenforcer Check STATE 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, verify that the services – TetSensor (for deep visibility) and TetEnforcer (for enforcement) – are running in the configured service context. See Verify that the agent is installed. |
||
Step 4 |
On the VDI instance VM, verify that the NPCAP driver is installed and running: Run command Run command Check STATE Running |
||
Step 5 |
On the VDI instance VM, verify that the agent is registered using a valid sensor_id:
|
Windows Agent Installer and Npcap
-
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 will install the supported version ten seconds after the service starts. If User has Npcap installed but is older than supported version, Npcap will not be upgraded. Up- grade/uninstall Npcap yourself, run the agent installer with 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 will try to upgrade Npcap at a later time.
-
Upgrade:
If Npcap is installed by Windows Agent and the version is older than the supported version, Npcap will be upgraded to the supported version ten seconds after the service starts. If Npcap driver is in use by any application, the agent will try to upgrade Npcap at a later time. If Npcap is not installed by Windows Agent, Npcap will not be upgraded.
-
Uninstall:
If Npcap is installed by Windows Agent, it will uninstall Npcap. If Npcap is installed by user, but upgraded by the agent installer with overwritenpcap=yes, it will not be uninstalled. If Npcap driver is in use by any application, the agent will not uninstall Npcap.
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 are required to install and execute the services.
-
Storage requirement for agent and log files: 500 MB.
-
Prevent other security applications from blocking agent installation or agent activity by configuring security exclusions on any security applications that are monitoring the host. See Security Exclusions.
-
AIX only supports flow capture of 20 net devices (6 net 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 this behaviour:
-
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 agent created bpf nodes and system bpf nodes will share the same major/minor, with each major/minor only be opened by one instance (either tcpdump or agent)
-
The agent will not access the system device nodes, and not create them as tcpdump does (tcpdump-D will create /dev/bpf0. . . /dev/bpf19 if they do not exist).
-
-
Running iptrace on system will prevent in certain scenarios flow capture from tcpdump and deep visibilty agent. This is a known design issue and needs to be checked with IBM.
-
To check if this scenarios exists before installing the agent, run tcpdump. If error message is like tcpdump: BIOCSETIF: en0: File exists iptrace is blocking flow capture. Stopping iptrace will resolve the issue.
-
-
Not every deep visibility functionality is supported on AIX. Package and process accounting are among the ones not supported.
-
-
Additional requirements for policy enforcement:
-
If IP Security Filter is enabled (i.e. smitty ipsec4), agent installation fails in pre-check. We recommend to disable IP Security Filter before installing agent.
-
When IP security is enabled, while Secure Workload enforcer agent is running, it will be reported as an error and enforcement agent will stop enforcing. To disable IP Security Filter when enforcement agent is active, contact a customer service representative.
-
Install AIX Agent using the Agent Script Installer Method
Deep visibility or enforcement AIX agents can only be installed using the Agent Script Installation method.
Note |
|
To install an AIX agent:
Procedure
Step 1 |
To navigate to the 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 |
(Optional) 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 automatically. 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 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 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 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.
-
In order 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. This usually 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. 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 which 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 to meet the requirements above:
-
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.
See the Felix configuration reference for more information on setting these options.
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 |
To 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 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 will attempt to read the file from its default location (~/.kube/config). However, it be specified explicitly with the --kubeconfig command line option. |
The installation script will provide instructions to verify the Secure Workload Agent Daemonset and 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, since the container runtime on those nodes uses its own proxy configuration. If the Docker images are unable to be pulled from the Secure Workload cluster, debugging the container runtime’s image pulling process will be necessary and adding a suitable HTTP proxy might be necessary. |
Installing Solaris Agents for Deep Visibility
Requirements and Prerequisites for Installing Solaris Agents
-
Root privileges are required to install and execute the services.
-
Storage requirement for agent and log files: 1 GB.
-
Prevent other security applications from blocking agent installation or agent activity by configuring security exclusions on the security applications that are monitoring the host. See Security Exclusions.
Install Solaris Agent using the Agent Script Installer Method
The installed Solaris agent supports both deep visibility and process/ package visibility.
Procedure
Step 1 |
To navigate to the 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 |
(Optional) 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 automatically. 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 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 pre-check, 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 command: |
||||||||
Step 2 |
Verify that you have a single entry as the output, which 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
In order for agents to register to the Secure Workload cluster, they require a cluster activation key. Additionally, if agents require an HTTPS proxy to reach the cluster, you must specify the proxy.
Note |
In Windows Environment, there is no need to configure user.cfg manually if activationkey and proxy options are used during manual installation. |
Before installation, configure the required variables in the user configuration file:
Procedure
Step 1 |
Retrieve your activation key: Go 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
Platforms supported by Cisco AnyConnect Secure Mobility agent with Network Visibility Module (NVM). No additional Secure Workload agent is required. 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
Endpoints registered with Cisco Identity Services Engine (ISE). No Secure Workload agent on the endpoint is required. 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 information, see ERSPAN Connector.
Integration with third-party and additional Cisco products
-
Integrations using external orchestrators configured in Secure Workload.
-
Integrations using connectors configured in Secure Workload.
See What are Connectors.
Connectivity Information
In general, when the agent is installed onto the workload, it starts making several network connections to the back-end services hosted on the Secure Workload cluster. Depending on the agent type and its functionality, the number of connections look different.
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 represents the IP address of the config server.
-
COLLECTOR-IP represents the IP address of the collector. Deep visibility and enforcement agents connect to all available collectors.
-
ENFORCER-IP represents 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 will be pulled from the Secure Workload cluster by every Kubernetes/Openshift node. These connections will be 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 |
|
It is important to note that if the workload is behind a firewall or the host firewall service is enabled, then the connections to the cluster might be denied. It is necessary for the administrators to allow such connections by creating appropriate firewall policies.