Agent Client Collector upgrade overview

  • Release version: Australia
  • Updated May 28, 2026
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Agent Client Collector upgrade overview

    The Agent Client Collector (ACC) Framework automates upgrades of ACC agents directly from your ServiceNow instance, eliminating the need for manual intervention on individual agent hosts. You can upgrade agents individually via the UI or upgrade all eligible agents simultaneously using an auto-upgrade feature. Each upgrade involves downloading the new version, installing, restarting the agent, and reporting the outcome back to the instance.

    Show full answer Show less

    Prerequisites and Setup

    • Configure the ACC web server and ensure the MID Server, MID Web Server, and websocket server are running.
    • Required role: agentclientcollectoradmin.
    • Use appropriate OS permissions for upgrades: Local SYSTEM on Windows, sudo rpm/dpkg on Linux, and sudo pkg on macOS.

    Upgrade Methods

    • Single agent upgrade: Upgrade agents one at a time or up to 50 simultaneously from the UI to validate upgrades before broader rollout.
    • Mass upgrade: Automatically upgrade all eligible agents using a scheduled job or background script with rate limiting to control rollout speed.

    Upgrade Process Stages

    1. InstanceVerification: Ensures agent eligibility by checking OS support, version, status, and MID Server connectivity.
    2. AgentVerification: Agent confirms it can upgrade by verifying permissions, disk space, and dependencies.
    3. Upgrade: Agent downloads the package, installs it, restarts, and reports success or failure.

    Agent Eligibility and Limits

    • Agents must be Up, running version 2.7.0 or higher but below the target version, not flagged as duplicates, have valid MID Server or Pod references, run supported OS, and not exceed retry limits.
    • Failed upgrade attempts are limited by the snagent.autoupgrade.retrylimit system property (default 3). After reaching this, agents are excluded from auto-upgrade but can be manually reset and upgraded selectively.

    Package Download Sources

    • Agents connected via Cloud Services (ICS) download from the ServiceNow CDN.
    • Agents connected via MID Server download packages locally; fallback to Install Server if MID Server is unavailable.
    • Custom download servers can be specified in the agent’s configuration file (acc.yml).

    Recommended Rollout Strategy

    • Start by upgrading a single agent via UI to validate the process.
    • Upgrade 5–10 agents from different OS environments for broader testing.
    • Perform full rollout using the scheduled job or background script for mass upgrades.

    Managing Upgrades

    • Selective upgrades are recommended for agents that are hard to access, including cloud-based agents, and allow upgrading up to 50 agents at once.
    • Mass upgrades use scheduled jobs or background scripts to upgrade all eligible agents with rate limiting.
    • Failed upgrades can be retried by clearing agent upgrade history or manually resetting failed attempts.

    Proxy Configuration for MID-less Upgrades

    • To secure upgrades of MID-less agents via CDN, configure proxy servers in the snagentproxy table in your instance.
    • This setup allows agents behind corporate proxies to download upgrade packages successfully.

    The Agent Client Collector Framework manages agent upgrades directly from the instance, with no manual action required on individual agent hosts.

    You can upgrade Agent Client Collector agents one at a time through the UI, or upgrade all eligible agents at once using the auto-upgrade feature. After an upgrade starts, each agent downloads the new version, installs it, restarts, and reports the result back to the instance.

    Before you upgrade

    Configure the Agent Client Collector web server. For details, see Configure the websocket server on the MID Server.

    Ensure that the MID Server, MID Web Server, and the MID Server websocket server are running.

    Roles required: agent_client_collector_admin
    • In a Windows environment: Local SYSTEM account
    • In a Linux environment: sudo rpm/dpkg
    • In a macOS environment: sudo pkg

    Upgrade methods

    Two upgrade methods are available:

    Single agent upgrade
    Upgrade one agent at a time from the agent record in the UI. Use this method to validate the upgrade process before a broader rollout. You can also select multiple agents from the list view to upgrade up to 50 agents at a time.
    Mass upgrade
    Upgrade all eligible agents automatically using the built-in scheduled job or a background script. The scheduled job applies rate limiting to control the rollout pace. The background script also uses rate limiting, and triggers an immediate upgrade without waiting for the next scheduled run.

    Upgrade stages

    Both single and mass upgrade attempts, progress through the following stages. Each stage creates a record in the Agent Upgrade Histories table.

    InstanceVerification
    The instance confirms the agent is eligible for upgrade. Checks include operating system support, agent version, agent status, and MID Server connectivity.
    AgentVerification
    The agent confirms it can perform the upgrade. Checks include permissions, available disk space, and dependencies.
    Upgrade
    The agent downloads the package, installs it, and restarts with the new version.

    For details on the required properties for agent overview, see Agent Client Collector upgrade properties.

    High-volume upgrade does not support Agent Client Collector to MID Server communication via mTLS.

    When performing high-volume upgrade, all agents that aren't using the most up-to-date version are upgraded. No upgrade is performed on agents already using the upgraded version.

    No upgrade is performed on agents that are outside the application scope. For more information, see Application scope.

    An agent is excluded from high-volume upgrade when you reach the failed upgrade limit for an agent. The failed upgrade limit is specified in the sn_agent.auto_upgrade.retry_limit system property. The default value for this property is 3.
    • This property applies to both high-volume and selective upgrades that have failed.
    • When an agent reaches the failed upgrade limit, an Agent Client Collector administrator can still run selective upgrade on the agent.
    • You can manually reset the failed upgrade limit by selecting the Reset failed upgrade attempts option on the agent page (select All > Agent Client Collector > Agents and select an agent).
    • After a successful upgrade, the upgraded agent is considered to have zero failed upgrades (for future upgrades).

    Agent eligibility

    An agent is eligible for auto-upgrade when it meets all of the following conditions:

    • Status is Up.
    • Version is 2.7.0 or higher and lower than the target upgrade version.
    • Agent is not flagged as a duplicate.
    • Has a valid MID Server or Pod reference.
    • Has not exceeded the retry limit for failed upgrades.
    • Runs on a supported operating system.

    Package download sources

    During upgrade, each agent downloads the new package from one of the following sources, depending on its connection type:

    • Agents connected via Cloud Services (ICS) download from the ServiceNow CDN at https://cdn-install.sncapps.service-now.com.
    • Agents connected via MID Server download from the MID Server directly over the local network.
    • If the MID Server is unavailable, agents fall back to the Install Server at https://install.service-now.com. To enable agent fallback, modify the base system checks to specify the install server as the download path. runUpgrade.rb --path=auto

    If your agents use a custom download server, configure the agent-upgrade-url-path key in the agent's acc.yml file. This setting takes priority over the default sources.

    Rollout strategy

    Use a phased approach to reduce risk when upgrading a large agent fleet:

    1. Upgrade one agent from the UI to confirm the process works end-to-end.
    2. Upgrade 5–10 agents from the list view, selecting agents across different operating systems.
    3. Perform a full rollout by enabling the scheduled job or running the background script.