Linux Proxy Agent - Remote Upgrades
LAST UPDATED: FEB 25, 2025
Starting from version 16.8.206.0, D3’s remote upgrading feature for the Linux Proxy Agent allows customer agents to update to the latest available version without perturbing ongoing tasks. This capability better ensures operational continuity and timely access to new features and security patches.
The Upgrading Process
Docker Foundations
The automatic upgrading process assumes pre-existing Linux Proxy Agent installation. The process includes downloading and installing three Docker containers: D3Agent, D3Executor and D3Installer.
Through a docker-compose.yml file, D3Agent and D3Executor are installed. The D3Installer, on the other hand, is dynamically installed during an update.
READER NOTE
As of July 2024:
Agent versioning aligns with the D3 vSOC versioning
Downgrading to a lower version is not permitted
To enable automatic agent updates, it is mandatory that your D3 vSOC is upgraded to version 16.8.206.0 or higher first.
Reach out to the D3 Support Team to schedule a D3 vSOC upgrade.
The agent container and agent installer require access to the Docker socket. They also must have permissions to execute Docker commands.
Agent Upgrade Workflow
Through a built-in task manager, D3 vSOC periodically monitors a status indicator in agents to determine whether any updates are necessary. Upon the release of a new agent version, the built-in task manager within D3 vSOC will pause all currently active tasks linked to the agent to avoid interference. In addition, new tasks are held until the upgrade completes.
Once Docker image files for the agent, executor, and installer are prepared and pushed to GCR, the agent upgrade can begin for version 16.8.206.0+ D3 vSOC instances by running the exec spPB_Job_StartAgentUpgrade SQL command in Microsoft SQL Server.
EXAMPLE
exec spPB_Job_StartAgentUpgrade '','16.8.206.0','16.8.206.0','16.8.206.0'Parameters (in sequence) | Description |
ProxyIds | The proxy token list separated by commas; applies to all agents if empty. |
ExecutorVersion | The updated executor version; can match the current version. |
AgentVersion | The updated agent version; must be newer than the current version. |
InstallerVersion | The installer version; can match the current version. |
When this SQL command is run, it initiates a sequence of actions within the D3 system.
Initially, the script scans and identifies all available Linux agents within the environment. It then uses the provided input parameters to construct necessary proxy data and updates the agent's ProxyData configuration accordingly. Subsequently, the script sets the agent's UpgradeState to 1, signaling a request for upgrade, and terminates execution.
When the agent's UpgradeState reaches 1 (request), the D3 vSOC task manager will verify the agent's RequestCount flag. If the agent's RequestCount flag is 0, indicating no active tasks, the task manager sets agent’s UpgradeState to 2 (ready), and queues an upgrade job. The upgrade job triggers a D3 vSOC REST API call to set their state to 3 (signal), prompting them to initiate the upgrade processes. Agents that receive these upgrade requests will perform a version comparison to ensure the update version is newer than the current one.
From here, the continued automation workflow is illustrated as follows:
Customer Action Plan
SaaS Solutions
To initiate the upgrade process, customers should first contact the D3 Support Team. Depending on their current version of D3 vSOC, the subsequent steps vary.
For those already using version 16.8.206.0 or higher, D3 Support handles the upgrade by simultaneously updating the customer's vSOC and triggering an automatic upgrade of the Linux Proxy Agent at the database level. Once completed, customers are promptly notified.
If a customer is using a version lower than 16.8.206.0, D3 Support will upgrade their D3 vSOC. Meanwhile, the customer must reinstall their Linux Proxy Agent by following the Proxy Agent Installation on Linux guide.
Once the D3 vSOC has been upgraded and the Linux Proxy Agent is of version 16.8.206.0 or higher, customers do not need to take any further action – the system will automatically apply subsequent upgrades.
On-Premises Solutions
The customer will initiate contact with the D3 Support Team, who will explain and clarify the course of action leading up to the execution of the spPB_Job_StartAgentUpgrade script.
The D3 Support Team supplies instructions, necessary packages, and dependencies for the customer to: upgrade their on-premises D3 vSOC, upgrade their Linux Proxy Agent, and execute the spPB_Job_StartAgentUpgrade script.
Customers already using version 16.8.206.0 or higher typically only need to initiate the Linux Proxy Agent upgrade using the spPB_Job_StartAgentUpgrade script, unless advised otherwise by D3.
Customers on a version lower than 16.8.206.0 must upgrade their vSOC, reinstall their Linux Proxy Agent by following the Proxy Agent Installation on Linux guide, and then trigger the Linux Proxy Agent upgrade via the spPB_Job_StartAgentUpgrade script.
In both cases, customers can coordinate with the D3 Support Team for assistance. D3 will notify customers once the setup is complete. The on-premises solution requires that the customer executes the spPB_Job_StartAgentUpgrade script when an upgrade is ready– a member of the D3 team will notify the customer when it is time.
Checking the Upgrade Status
Ensure that your Linux Proxy Agent is version 16.8.206.0 or higher.
If it is not, refer to Linux Proxy Agent installation guide to upgrade.
If your Linux Proxy Agent is already version 16.8.206.0 or higher, the agent auto-upgrade will take effect automatically after your vSOC upgrade.
Observe your agent version, upgrade status and upgrade message on the Agent Management page.
Click on the Configuration navigational tab.
Click on the Agent Management menu item.
Select your agent within the agent table.
Observe your agent’s version underneath the Agent Details section.
Observe your agent’s upgrade state.
Observe your agent’s upgrade message.
READER NOTE
If an agent upgrade fails:
An Upgrade button will render on the top-right hand side.
The upgrade state will show as "Error".
A detailed upgrade message will be displayed.
See the Addressing Upgrade Errors section
Manually click on the 
button to retry the upgrade process should the auto-upgrade process fail.
READER NOTE
The Save button remains unaffected by upgrade failures since it is used solely for saving the agent description. Therefore, it will always be visible.
During the upgrade process, if you see Requesting or Upgrading as your agent's Upgrade State, the upgrade is underway.
Once the Upgrade State changes to N/A, the agent upgrade process is complete. Verify the version to confirm the successful upgrade.
If all upgrade attempts fail, please contact D3 for assistance. Our support team is here to help resolve issues and ensure your agents are updated.
Addressing Upgrade Errors
Error Message: "Connection Failed"
The Docker group ID specified in the Docker Compose file is incorrect. To obtain the <Docker Group ID>, execute the following command in Linux:
getent group docker | cut -d: -f3Error Message: "Docker API responded with status code=NotFound, response={"message":"manifest for gcr.io/emerald-ellipse-332519/dev/d3agent:<Agent Version Number> not found: manifest unknown: Failed to fetch \"<Agent Version Number>\" from request \"/v2/emerald-ellipse-332519/dev/d3agent/manifests/1<Agent Version Number>\"."}"
The agent image is unavailable. Please reach out to D3 to verify whether the upgraded agent image exists.
Error Message: “Create executor error: Can’t find binding port”
The old executor was not found. Follow these steps to troubleshoot:
Verify in Docker whether the old executor exists, regardless of its state.
Examine the container image name of the old executor; if it does not include 'd3executor', that may be the cause of the issue.
Review the port binding configuration of the old executor container.
Error Message: "The new version is older than the current version. Cancel the upgrade."
The agent upgrade version is incorrect. Upgrades are only supported when transitioning from a lower to a higher version. Please contact D3 for assistance.
Error Message: "The new agent version matches the current version. Cancel the upgrade."
The agent upgrade version is incorrect. Upgrades are only supported when transitioning from a lower to a higher version. Please contact D3 for assistance