Skip to main content
Data Infrastructure Insights

Deploy Workload Security Agents

Contributors netapp-alavoie dgracenetapp
PDFs

Workload Security Agents monitor user activity and detect potential security threats across your storage infrastructure. This guide covers installing an Agent, opening the required network ports, managing pause/resume and pin/unpin behavior, and verifying the Agent after deployment. Before you begin, ensure the Agent host meets the requirements in Workload Security Agent Requirements.

Before you begin

  • Confirm the Agent host meets the system, package, and network requirements in Workload Security Agent Requirements (4 CPU cores, 16 GB RAM, /opt/netapp with at least 35 GB free, supported Linux distribution, unzip / zip / sshpass, static IP, NTP).

  • sudo privilege is required for installation, running scripts, and uninstall.

  • During installation, a local user cssys and a local group cssys are created on the machine. If policy does not allow creating a local user and instead requires Active Directory, create a user with the username cssys in Active Directory before you install.

  • An Agent supports a maximum of 50 data collectors (all types combined — for example Active Directory, LDAP, and ONTAP SVM collectors), within a ceiling of about 20,000 events per second. Plan capacity with the Event Rate Checker before deploying many collectors on one Agent.

  • If the Agent will use a proxy to reach SaaS, have the proxy host, port, and credentials ready. You set the proxy during installation, in step 4.

Steps to install an Agent

  1. Log in as Administrator or Account Owner to your Workload Security environment.

  2. Select Collectors > Agents > +Agent. The system displays the Add an Agent page.

The Add Agent page, with proxy server settings and the installer snippet expanded.

The Add Agent page showing Agent Server Requirements

  1. In the Agent Server Requirements panel, click Linux Versions Supported (i) and Minimum Server Requirements (i) to confirm the host OS is supported and correctly sized.

Minimum Server Requirements: 4 CPU cores, 16 GB RAM, 35 GB free disk space.

Minimum Server Requirements tooltip showing 4 CPU cores

  1. If your network uses a proxy server, expand Optional: Proxy server settings > Show Instructions and click Copy Proxy Server Settings. On the Agent host, run the copied command in a terminal, replacing USER, PASSWORD, PROXY_SERVER, and PORT with your own values:

export https_proxy='USER:PASSWORD@PROXY_SERVER:PORT'

Run this command in the same terminal that you use for the installer snippet, so that the installer inherits the proxy setting.

  1. Click Copy Installer Snippet. The snippet contains a unique key that is valid for 2 hours and for one Agent only, so run it promptly and do not reuse it for a second Agent. To inspect it first, click Reveal Installer Snippet.

  2. On the Agent host, open a terminal, paste the installation command, and run it. Prefer an empty working directory you own (for example mkdir cloudsecure && cd cloudsecure) so chmod during install does not fail on files owned by other users.

  3. When installation completes successfully, the installer prints a success message and the Agent service starts. Return to the browser and click Complete Setup to finish adding the Agent. "New agent detected" will be displayed on successful installation.

After you finish

  • Confirm the Agent appears Connected on Workload Security > Collectors > Agents.

  • Open the FPolicy/EMS callback ports on the Agent host (see Network configuration below).

  • Configure a User Directory Collector (Active Directory or LDAP) for each domain whose users touch monitored SVMs — ideally before or with the first ONTAP SVM collector. Without it, Activity Forensics may show SIDs instead of usernames. Test Connection is not available for User Directory collectors.

  • Configure one or more ONTAP SVM Data Collectors. Prefer Cluster management IP + SVM name with cluster credentials, and run Test Connection before saving so network and RBAC checks pass.

  • Stay within Agent capacity: at most 50 collectors per Agent; use the Event Rate Checker to size for peak event rate.

Change the proxy after installation

If the proxy changes after the Agent is installed, update the Agent configuration and restart the service.

  1. Change to the configuration directory: cd /opt/netapp/cloudsecure/conf

  2. Edit agent.properties and set AGENT_PROXY_HOST, AGENT_PROXY_PORT, and if required AGENT_PROXY_USER and AGENT_PROXY_PASSWORD.

  3. Restart the Agent: sudo systemctl restart cloudsecure-agent.service

If the Agent is behind SSL inspection (for example Zscaler), disable SSL inspection for *.cloudinsights.netapp.com and the regional agentlogin host. Workload Security does not work correctly when intermediary certificates re-sign the SaaS endpoints.

Network configuration

Open the TCP ports that ONTAP uses to send FPolicy (and EMS) events to the Agent. You do not need to open the entire 35000–55000 range. Size the reservation to collectors on this Agent: each SVM uses up to 4 ports (2 per enabled protocol — NFS and CIFS/SMB). For a fully loaded Agent (50 collectors), reserve about 200 ports within 35000–55000. Increase the reservation if needed.

Open the range toward the Agent host, including any local firewall. Also ensure SVM data LIFs can reach the Agent for FPolicy events, and (if you use EMS-based features such as ARP) that the cluster management IP can reach the Agent on the same reserved ports. See Workload Security Agent Requirements for the full in-network and cloud egress tables.

Example — firewalld (permanent):

sudo firewall-cmd --permanent --zone=public --add-port=35000-55000/tcp

sudo firewall-cmd --reload

Verify the rule:

On systems using firewalld (for example RHEL / CentOS 8+):

sudo firewall-cmd --zone=public --list-ports | grep 35000

Sample output: 35000-55000/tcp

On systems using iptables (for example older RHEL / CentOS 7.x):

sudo iptables-save | grep 35000

Sample output:

-A IN_public_allow -p tcp -m tcp --dport 35000:55000 -m
conntrack -ctstate NEW,UNTRACKED -j ACCEPT

Test Connection (on the ONTAP SVM collector page) verifies only a subset of ports in this range. Keep the full reserved set open on the Agent.

Post-install verification

After a successful install, confirm the following on the Agent host and in the UI:

  • UI state: Collectors > Agents shows the Agent as Connected (not NOT_CONNECTED).

  • Service: sudo systemctl status cloudsecure-agent.service reports active (running).

  • User: id cssys and groups cssys succeed (local cssys user/group exist, or the AD cssys account is available).

  • Disk path: /opt/netapp is on local disk that cssys can access (not an NFS mount the local user cannot use).

  • Ports: The reserved 35000–55000 subset is open inbound to the Agent (firewall-cmd or iptables check above).

  • SaaS path: Outbound TCP 443 to your region’s *.cloudinsights.netapp.com and agentlogin endpoints succeeds (no SSL-inspection rewrite).

If the Agent fails to start before application logs exist, check journalctl -u cloudsecure-agent.service — early bootstrap errors go to the service journal, not agent.log.

Control Agent upgrades: pin and unpin

By default, Workload Security updates Agents automatically. Pinning an Agent pauses those automatic updates, so the Agent and the collectors it hosts stay at their current version.

Note: Pin and unpin apply to an Agent and are available only through the API. Pause and Resume are collector controls — they do not apply to an Agent — and you can run them from either the UI or the API. See Configuring the ONTAP SVM Data Collector.
_

Control How you run it What it does

Pin

cloudsecure_config.agents API only.

Not available in the UI.

Pauses automatic updates. The Agent and the collectors it hosts stay at their current version.

Unpin

cloudsecure_config.agents API only.

Not available in the UI.

Resumes automatic updates. The Agent retrieves the latest available version and upgrades itself and its collectors.

A pinned Agent returns to automatic updates when either of the following happens:

  • You unpin the Agent.

  • 30 days have passed. The 30-day window starts on the day of the most recent Agent update, not on the day you pin the Agent.

In either case, the Agent updates at the next Workload Security refresh after the condition is met. Allow up to five minutes for a pin or unpin request to take effect.

To pin or unpin an Agent, use the cloudsecure_config.agents APIs. You can view current Agent versions on Workload Security > Collectors > Agents.

Agent pin and unpin APIs

Pin and unpin APIs in the cloudsecure_config.agents category.

Agent versions

Agent versions displayed on the Agents tab.

Pin and unpin one Agent at a time

Pinning and unpinning are also supported at the tenant level. If you unpin at the tenant level, every Agent in the tenant is upgraded automatically and immediately.

Use Agent-level pin and unpin instead. Agent-level control is more granular: only the Agent you unpin receives the upgrade, so the effect of a new version is contained to that Agent and the collectors it hosts.

Scope Pin Unpin

All Agents in the tenant

POST /v1/cloudsecure/agents/configuration

DELETE /v1/cloudsecure/agents/configuration

A single Agent (recommended)

POST /v1/cloudsecure/agents/

{agentId}/configuration

DELETE /v1/cloudsecure/agents/

{agentId}/configuration

Suggested approach

  1. Pin the Agents you want to hold at their current version.

  2. Unpin one Agent and let it upgrade.

  3. Confirm that the Agent returns to Connected and that its collectors return to Running.

  4. Unpin the remaining Agents in batches, so that an unexpected problem affects only part of your environment.

Best practices for Agents

These practices apply to the Agent. For collector practices, including
when to pause a collector, see Configuring the ONTAP SVM Data Collector.

  • Use pin and unpin to control when an Agent upgrades. You do not need to pause collectors for upgrade control.

  • Pin and unpin at the Agent level rather than the tenant level, so that an upgrade affects one Agent and its collectors at a time.

  • Do not plan to stay pinned indefinitely. A pinned Agent updates automatically 30 days after its most recent update.

  • Stay within Agent capacity: at most 50 collectors per Agent (all types combined), within a ceiling of 20,000 events per second. Approximately 10 collectors suit 4 CPU cores and 16 GB RAM; approximately 20 collectors suit 4 CPU cores and 32 GB RAM.

  • Size the Agent for peak event rate with the Event Rate Checker before you add collectors, and migrate a collector to another Agent rather than overloading one Agent.

  • Distribute collectors across Agents so that maintenance on one Agent does not stop monitoring for every SVM.

  • Give the Agent host a static IP address, and keep its clock synchronized with ONTAP using NTP.

  • Keep the reserved FPolicy callback ports open toward the Agent, including in the host firewall (see Network configuration).

Troubleshooting

For Agent install and connectivity failures (unsupported OS, missing unzip/zip, cssys permission issues, NOT_CONNECTED, proxy changes, symptom-collector failures), see Troubleshooting the ONTAP SVM Data Collector — Agent install and health section, and Workload Security Agent Requirements.

To collect a diagnostic bundle for Support (run as root):

sudo
/opt/netapp/cloudsecure/agent/bin/cloudsecure-agent-symptom-collector.sh
-o /tmp

Attach cloudsecure-agent-symptoms.zip (or the zip created in /tmp) to the case, along with your Data Infrastructure Insights serial number. Ensure the zip package is installed on the Agent host before running the symptom collector.