Upgrade Software Agents

During the software agent upgrade process:

  • All its processes terminate and are replaced with a new version.

  • Flows are not captured during the upgrade.

  • If the agent was enforcing a policy, the policy remains enforced on the workload.

When the new version of agent starts:

  • The allowed/denied flow capture resumes.

  • The flows are stored to disk until the agent is connected to the collectors (CLC). This applies unless the Flow Disk Quota configuration is turned off.

Before the enforcement process reconnects to the Endpoint Firewall Enforcement (EFE), it ensures that the last received and enforced policy remains intact in the Secure Workload's firewall.

Upgrade agents using the UI

Upgrade software agents to the latest available version using either automatic workflow-based upgrade or manual upgrade from the UI.

Agents can be upgraded using Agent Config Intent workflow as described in Software Agent Config. While configuring an agent config profile, there is an Auto Upgrade option which can be enabled or disabled. If the option is enabled, the agents matching inventory filter criteria are automatically upgraded to the latest available version.

On the Software Agents > Agent List page, software agents with outdated versions are highlighted with a warning sign under the SW Version column. Upgrade these agents to the latest available version on the cluster.

To use software agent config intent workflow to configure software agent upgrade:

Procedure

Step 1

Create an inventory filter on the Inventory Filters page. For more information, refer to Filters.

Figure 1. Inventory Filter
Inventory Filter

Step 2

Create an agent config profile for the agents selected by the inventory filter. Optionally, you can enable the Auto Upgrade option to automatically upgrade the selected agents.

Figure 2. Agent Config
Agent Config

Step 3

Create an agent config intent to apply the config profile to the agents selected using inventory filter. If the auto upgrade option is enabled, the selected agents are automatically upgraded.

It normally takes up to 30 minutes to upgrade an agent after an agent profile is applied to them.

Figure 3. Agent Config Intent
Agent Config Intent

Note

 

Auto Upgrade setting in the default agent profile applies to ERSPAN. All other connector agents are auto upgraded whenever there is a cluster upgrade, including patch releases.

Manually upgrade software agents

Use this procedure to manually upgrade one or more Deep Visibility or Enforcement agents to a selected software version.

Procedure

Step 1

In the navigation pane, choose Manage > Workloads > Agents.

Step 2

On the Agent List page, choose the page menu and select Upgrade.

Step 3

Select the target agent version from the version list. Confirm that the list displays only agents eligible for the selected version.

Step 4

Optionally enter a search query in the filter field. For example, enter Platform = CentOS-7.6.

Step 5

Select the agents to upgrade, and choose Upgrade.

Deep visibility and enforcement agents appear. For each agent, only the newer versions you can upgrade to are listed. The latest version is selected by default.

Note

 

Automatic upgrades through the Agent Config Intent workflow are recommended for most deployments. This procedure describes manual upgrades through the user interface. If you manually download and deploy an agent package, follow the applicable safety precautions.

Kubernetes/Openshift agent upgrade behaviors

Agents installed on Kubernetes/Openshift nodes using the daemonset installer script are capable of self-upgrade. The upgrade process is controlled by either the auto-upgrade option or by manually triggering an upgrade for any node in the Kubernetes/Openshift cluster. The mechanism of the upgrade in this environment is to upgrade the Docker image in the daemonset specification, which means that an upgrade of one agent affects all agents covered by the daemonset, as explained in the next paragraph.

When a Daemonset Pod specification changes, Kubernetes/Openshift will trigger a graceful shutdown, fetch the new docker image(s) and start the Secure Workload agent pods on ALL nodes in the Kubernetes/Openshift cluster. This will cause agents to be upgraded on other nodes, even if the policy to allow upgrades is applicable only to a subset of the nodes in the cluster.

If auto-upgrade is disabled for all nodes, manual upgrade is possible by downloading a new installer script and re-running the install. The installation script auto-detects the case of new installation vs upgrading an existing installation and will work to manually upgrade the daemonset pods when it detects an installation is already in place.

Remove the Deep Visibility or Enforcement Linux Agent

RPM based installation

Run the command: rpm -e tet-sensor.

Agent uninstallation event is communicated to the cluster and the agent will be marked as uninstalled in the Software Agent page.

Manually delete the agent from UI on the Software Agent page or the user can enable automated cleanup or removal of the agent by turning on the cleanup period from agent config profiles.


Note

By default, the cleanup period is turned off.

Ubuntu.deb based installation

Fresh installation of Ubuntu agents now uses the native .deb format.

Run the command: dpkg –purge tet-sensor

Agent uninstallation event is communicated to the cluster and the agent will be marked as uninstalled in the Software Agent page.

Manually delete the agent from the Software Agent page or the user can enable automated cleanup or removal of the agent by turning on the cleanup period from agent config profiles.


Note

  • By default, the cleanup period is turned off.

  • During the agent operations, it is possible that some kernel modules will be loaded automatically by the kernel. For example, if enforcement is enabled in Linux, Netfilter modules might be loaded. Agents do not have a list of modules loaded by kernel. Therefore, during agent uninstallation, it cannot possibly unloaded the kernel modules.

  • If enforcement agent applied a policy to the system firewall, uninstalling agent clears the applied policy and opens the system firewall.

Figure 4. Agent uninstallation alert
Agent uninstallation alert

Uninstall a Deep Visibility or Enforcement Windows agent

Use this task when you need to remove an agent from a system for maintenance, replacement, troubleshooting, or security reasons. This procedure is applicable to Cisco Secure Workload agents for Deep Visibility or Enforcement on Windows. There are two options to uninstall Secure Workload agents:

Procedure

Step 1

Navigate to Control Panel > Programs > Programs and Features, and uninstall Cisco Secure Workload Agent.

Step 2

Alternatively, run the shortcut Uninstall.lnk within. 

C:\Program Files\Cisco Tetration

Step 3

If an enforcement agent applies a policy to the system firewall, uninstalling the agent clears the applied policy, and opens the system firewall.

After you have uninstalled the agent, the cluster information is updated. The status of the agent is updated in the Software Agent page and the agent is marked as uninstalled.

Manually delete the agent from the Software Agent page or user can enable automated cleanup or removal of the agent by activating the cleanup period in the agent config profiles.

Note

 

By default, keep the cleanup period turned off.

Note

 

  • If you have installed Npcap during agent installation, Ncap will also get uninstalled while uninstalling the agent.

  • By default, log files, config files and certs will not get removed during uninstall. If you want to remove them, run the shortcut UninstallAll.lnk in the same folder.

Uninstall the deep visibility agent or enforcement AIX agent

Remove the deep visibility agent or enforcement AIX agent from your AIX system and ensure that related agent files and configurations are cleared. This procedure involves removing the agent, optionally deleting the installation directory, and clearing any applied policies.

Procedure

Step 1

To uninstall a software agent, run the command:

installp -u tet-sensor

After the software agent is uninstalled and is no longer available on the UI, this information is communicated to the cluster, and the agent is marked as Uninstalled in the Software Agent page.

Step 2

There are two ways in which you can delete an agent from the UI:

  • Delete the agent that is no longer needed directly from the Software Agent page. Additionally, you can delete the Tetration agent installation directory /opt/cisco/tetration by running the following command: 

    rm -rf /opt/cisco/tetration

  • Configure the cleanup period in the Agent Configuration Profiles page to enable automated cleanup.

Note

 

  • By default, the cleanup period is set to Off.

  • The System Resource Controller controls the Deep Visibility agent as tet-sensor. You can start, stop, restart, and delete it. The service is made persistent with inittab as tet-sen-engine.

  • The System Resource Controller controls the Enforcement agent as tet-enforcer. You can start, stop, restart, and delete it. The service is made persistent with inittab as tet-enf-engine.

  • During the agent operations, the kernel may load some kernel modules automatically. For example, if enforcement is enabled in AIX, ipfilter modules are loaded. Agents do not have a list of modules loaded by the kernel. Therefore, during agent uninstallation, it cannot unload the kernel modules.

  • If the Enforcement agent applied a policy to the system firewall, uninstalling the agent clears the applied policy and opens the system firewall.

Uninstall the Universal Linux agent

Use this task when you need to uninstall the Universal Linux Agent from your Linux environment and remove it from your management console.

Procedure

Step 1

Run the uninstall script: ‘/usr/local/tet-light/uninstall.sh‘

Step 2

Delete the agent from the Software Agent page.

Remove the Universal Windows agent

Use this task to uninstall the Universal Windows Agent and clean up associated records to ensure it is fully uninstalled from your system.

Procedure

Step 1

Run the uninstall script: ‘C:\Program Files\Cisco Tetration\Lightweight Sensor\uninstall.cmd‘

Step 2

Delete the agent from the Software Agent page.

Uninstall an Enforcement Kubernetes or OpenShift agent

Procedure

Step 1

Locate the original installer script or download a new script from the Secure Workload UI.

Step 2

Run the uninstall option: install.sh –uninstall. Consider the same points you did when installing.

  • Only supported on Linux x86_64 architectures.

  • Either ensure that ~/.kube/config contains an admin credentials user or use the –kubeconfig option to specify the kubectl admin credentials file.

Step 3

Delete the agents for all the Kubernetes nodes from the Software Agent page.

Remove a Deep Visibility Solaris agent

Perform this task to uninstall the Deep Visibility Solaris agent.

Procedure

Step 1

To uninstall a software agent, run the following command:

  • For Solaris 11.4: pkg uninstall tet-sensor

  • For Solaris 10: pkgrm -a /opt/cisco/secure-workload/noask.admin -n tet-sensor

Step 2

Delete the agent from the Software Agent page.

Enable agent rehoming

Agent rehoming allows agents to be transferred to a new destination scope and sensor configuration. This is often required during environment changes or to improve workload distribution. Use these steps to enable agent rehoming to migrate agents to a different scope and sensor setup.

Procedure

Step 1

In the left navigation menu, click Manage > Workloads > Agents.

Step 2

Click the Agent List tab.

Step 3

Click the menu icon and select Rehome Agents.

Figure 5. Rehome agents
Rehome agents

Step 4

On the Agent Rehoming window, fill these details:

Field

Description

Destination Scope Activation Key

  1. Navigate to Manage > Workloads > Agents.

  2. Click the Installer tab.

  3. Select Manual install using classic packaged installers.

  4. Click Next.

  5. Click Agent Activation Key.

  6. Copy the Key value and paste it into the Destination Scope Activation Key field.

Destination Sensor VIP

  1. Navigate to Platforms > Cluster Configuration.

  2. Copy the Sensor VIP and paste it into the Destination Sensor VIP field.

HTTPS proxy

Enter a proxy domain or address if the agent needs to use a proxy for outbound communication.

to use a proxy for outbound communication.

Destination Sensor CA Cert

  1. Navigate to Platforms > Cluster Configuration.

  2. Rehome agents
Figure 6. Enable agent rehoming
Enable agent rehoming

Step 5

Click Enable Agent Rehoming.

The configuration is saved. The Rehome button appears at the top right.

Rehome agents

Use this task when you need to reassign agents within your system, such as during server migration or restructuring.

Procedure

Step 1

Select an agent.

Step 2

Click Rehome.

Figure 7. Select Agents to Rehome

Step 3

Confirm by clicking Yes.

The selected agent is now rehomed to the specified location or server.

Disable Rehoming

Disabling tenant rehoming ensures that appliance or tenant settings are cleared before enabling rehoming for another user. This procedure is especially useful when managing multiple users rehoming to or from SaaS.

Note

If there are multiple users rehoming to or from SaaS, the site administrator has to move each tenant or an appliance separately. To do this, disable Rehoming to clear the settings, and then enable Rehoming for the new user.

Procedure

Step 1

Click the menu icon and choose Rehome Agents.

Step 2

On the Agent Rehoming window, click Disable Agent Rehoming.

Figure 8. Disable Agent Rehoming
Disable Agent Rehoming