--- sourceDocument: Australia IT Operations Management sourceDocumentLink: https://www.servicenow.com/docs/r/australia/it-operations-management Release : - australia ft:locale : - en-US ft:publication_title : - Australia IT Operations Management ft:clusterId : - itom bundleId : - itom workflow : - Technology --- # Agent Client Collector upgrade overview # Agent Client Collector upgrade overview {#ariaid-title1} Release version: Australia Updated May 28, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 Framework enables automated upgrades of Agent Client Collector agents directly from the ServiceNow instance, eliminating the need for manual updates on individual hosts. Upgrades can be done one agent at a time via the UI or in bulk using an auto-upgrade feature. During the upgrade, each agent downloads the new version, installs it, restarts, and reports the status back to the instance. Show full answer Show less ## Upgrade Preparation * Configure the Agent Client Collector web server and ensure the MID Server, MID Web Server, and MID Server websocket server are operational. * Required roles include **agentclientcollectoradmin**. * Platform-specific permissions are necessary, such as Local SYSTEM account on Windows or sudo privileges on Linux/macOS. ## Upgrade Methods * **Single Agent Upgrade:** Upgrade one agent from its record in the UI, or select up to 50 agents from the list to upgrade simultaneously. Useful for validating the upgrade process before broader rollout. * **Mass Upgrade:** Automatically upgrade all eligible agents using a scheduled job or a background script with rate limiting to manage the rollout pace. ## Upgrade Process Stages * **InstanceVerification:** Verifies agent eligibility based on OS support, version, status, and MID Server connectivity. * **AgentVerification:** Checks on the agent side for permissions, disk space, and dependencies. * **Upgrade:** Downloads, installs, restarts the agent, and reports the result. ## Agent Eligibility and Constraints * Agents must have status "Up," run supported OS, have valid MID Server or Pod references, be within version bounds, and not exceed the retry limit for failed upgrades. * Agents already at the target version or outside the application scope are excluded from upgrades. * Failed upgrade attempts are limited by the **snagent.autoupgrade.retrylimit** property (default 3). Administrators can reset failure counts manually. ## Package Download Sources * Agents connected via Cloud Services download from the ServiceNow CDN. * Agents connected via MID Server download directly from the MID Server or fallback to the Install Server if the MID Server is unavailable. * Custom download servers can be configured via the **agent-upgrade-url-path** key in the agent's configuration file. ## Rollout Strategy Recommendations * Begin with upgrading a single agent through the UI to validate the process. * Upgrade a small batch (5--10 agents) from different OS environments. * Proceed with a full rollout using scheduled jobs or background scripts with rate limiting. ## Upgrade Execution Options * **Selective Upgrade:** Efficient for agents that are difficult to access; supports upgrading up to 50 agents simultaneously. * **Mass Upgrade:** Uses a scheduled job for automatic upgrades or a background script for immediate upgrades of eligible agents. * Failed agents can be targeted for re-upgrade after clearing their upgrade history. ## Additional Configuration * **Proxy Configuration:** To enhance security and support upgrades of MID-less agents via CDN, proxy servers can be added to the **snagentproxy** table. * Proxy entries help agents behind corporate firewalls download upgrade packages from the ServiceNow CDN. 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.{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-1} ## Before you upgrade {#acc-agent-upgrade-overview__section_otg_jht_pjc} Configure the Agent Client Collector web server. For details, see [Configure the websocket server on the MID Server](https://www.servicenow.com/docs/4nNClTmkpFQEOh5mUpDcBA "Configure the websocket server on MID Servers to enable connections from agents to the MID Server. You can configure only one websocket server per 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 {#acc-agent-upgrade-overview__ul_pbl_5w3_y2c} ## Upgrade methods {#acc-agent-upgrade-overview__acc-agent-upgrade-overview-upgrade-methods} Two upgrade methods are available:{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-2} 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 {#acc-agent-upgrade-overview__acc-agent-upgrade-overview-upgrade-stages} Both single and mass upgrade attempts, progress through the following stages. Each stage creates a record in the Agent Upgrade Histories table.{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-3} 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](https://www.servicenow.com/docs/OxsEu9uoR2ahrCuWRXo5bQ "System properties that control Agent Client Collector upgrade behavior, including the target version, rate limits, retry logic, and timeouts."). Selective upgrade doesn't 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](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=australia&pubname=australia-application-development&ft:locale=en-US). 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 AllAgent Client CollectorAgents and select an agent). * After a successful upgrade, the upgraded agent is considered to have zero failed upgrades (for future upgrades). {#acc-agent-upgrade-overview__ul_ejj_3qp_chc} ## Agent eligibility {#acc-agent-upgrade-overview__acc-agent-upgrade-overview-eligibility} An agent is eligible for auto-upgrade when it meets all of the following conditions:{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-4} * 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. {#acc-agent-upgrade-overview__ul_acc_upgrade_eligibility} ## Package download sources {#acc-agent-upgrade-overview__acc-agent-upgrade-overview-download-sources} During upgrade, each agent downloads the new package from one of the following sources, depending on its connection type:{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-5} * 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 {#acc-agent-upgrade-overview__ul_acc_upgrade_download} 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.{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-6} ## Rollout strategy {#acc-agent-upgrade-overview__acc-agent-upgrade-overview-rollout} Use a phased approach to reduce risk when upgrading a large agent fleet:{#acc-agent-upgrade-overview__acc-agent-upgrade-overview-para-7} 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. {#acc-agent-upgrade-overview__ol_acc_upgrade_rollout} * **[Upgrade an agent in an instance](https://www.servicenow.com/docs/0qP2qGwY2dUShIYbzAUywQ)** Perform selective self-upgrade instead of bulk upgrade for enhanced efficiency when working with agents that are difficult to access, such as agents deployed in the cloud. You can perform selective upgrade on up to 50 agents at a time. * **[Upgrade multiple agents in an instance](https://www.servicenow.com/docs/1TkdRlXdsh9n9C~w8m4ZxQ)** When performing selective upgrade of an agent in an instance, you can select multiple instances to upgrade at once. * **[Run a mass upgrade via the scheduled Agent Client Collector upgrade job](https://www.servicenow.com/docs/K9qVAtCO_lvMFtO~9GgWXg)** Activate the built-in scheduled job to upgrade all eligible Agent Client Collector agents automatically in rate-limited batches. * **[Run a mass Agent Client Collector upgrade using a background script](https://www.servicenow.com/docs/WUawmvBnaCQj87kKc0vMGA)** Trigger an immediate upgrade of all eligible Agent Client Collector agents without waiting for the next scheduled job run. * **[Repeat high-volume upgrade for failed agents](https://www.servicenow.com/docs/XTWKeW2eQ7~5_BucVmq4Ig)** If high-volume upgrade fails for specific agents, you must clear the problematic agents' history to re-enable upgrade. If the target upgrade version changes, you don't need to clear the agents' history, as the agents upgrade with the next scheduled high-volume upgrade. * **[Configure proxies during MID-less upgrade using a CDN](https://www.servicenow.com/docs/7LHGl33uRrwLoiaicd5cMg)** Create proxies for added security when upgrading MID-less agents via a Content Delivery Network (CDN). You add proxy servers to the sn_agent_proxy table on the ServiceNow instance. * **[Configure a download proxy for Agent Client Collector upgrades](https://www.servicenow.com/docs/GpJ8vn7QBEDuK5h1geb3uQ)** Add a proxy server entry so that agents behind a corporate proxy can download upgrade packages from the ServiceNow Content Delivery Network (CDN). *[\>]: and then