Agent upgrade module
The agent upgrade module is responsible for carrying out the entire agent upgrade process remotely:
On the manager side, it validates, downloads, and/or sends the WPK files to the agents.
On the agent side, it processes the received commands and sends a notification to the manager after an upgrade process has been accomplished.
The following is a description of how the agent upgrade module works.
Upgrade request [API/CLI]
The agent upgrade module will receive the upgrade requests from a socket located at:
{WAZUH_DIR}/queue/tasks/upgrade
The module expects 3 parameters:
Option |
Suboption |
Values |
Description |
---|---|---|---|
origin |
module |
api (only value allowed) |
Emiter of the request |
command |
upgrade, upgrade_custom |
Specifies the command to be executed |
|
parameters |
agents |
Array of int values (id of the agents) |
Specifies the list of agents where the command will be applied |
Upgrade parameters: Command to upgrade agents from a repository.
Option
Suboption
Values
Required
Default
Description
parameters
wpk_repo
string
no
<wpk_repo>
configurationParameter to override the default WPK repository set by configuration
version
vX.Y.Z
no
Last available version
Overrides the version of the package that will be downloaded from the repository
use_http
true, false
no
false
Whether retrieve the WPK file over http or https
force_upgrade
true, false
no
false
Forces the agents to upgrade, ignoring version validations
Example message:
{ "origin": { "module": "api" }, "command": "upgrade", "parameters": { "agents": [5,6], "wpk_repo": "packages.wazuh.com/wpk/", "version": "v4.2.1", "use_http": false, "force_upgrade": false } }
Upgrade custom parameters: Command to upgrade agents from a local WPK file.
Note
In case of having a multi-node ThreatLockDown cluster, the custom WPK file has to exist on all nodes in the specified path.
Option
Suboption
Values
Required
Default
Description
parameters
file_path
string
yes
Path to the WPK file to be sent
installer
string
no
upgrade.sh
in Linux and macOS,upgrade.bat
in WindowsOverrides the default installer script
Example message:
{ "origin": { "module": "api" }, "command": "upgrade_custom", "parameters": { "agents": [20,23], "file_path": "/home/user/agent.wpk", "installer": "custom-upgrade-script.sh" } }
Upgrade result request [API/CLI]
The task manager is the one that informs the result of an upgrade task. It will receive the upgrade result requests from a socket located at:
{WAZUH_DIR}/queue/tasks/task
Note
In case of having a multi-node ThreatLockDown cluster, the task manager only runs on the master node. This request should always go to the master node.
The module expects 3 parameters:
Option |
Suboption |
Values |
Description |
---|---|---|---|
origin |
module |
api (only value allowed) |
Emiter of the request |
command |
upgrade, upgrade_custom |
Specifies the command to be executed |
|
parameters |
agents |
Array of int values (id of the agents) |
Specifies the list of agents where the command will be applied |
Example message:
{
"origin": {
"module": "api"
},
"command": "upgrade_result",
"parameters": {
"agents": [5,10]
}
}
The response will contain all the information related to the upgrade task stored in the tasks DB:
Option |
Values |
Description |
---|---|---|
error |
int value |
Error code: 0 when success, a positive number when error |
data |
array |
Array with the responses for each agent |
message |
string |
String associated to the error code |
The information for each agent will be the following:
Option |
Values |
Description |
---|---|---|
error |
int value |
Error code: 0 when success, a positive number when error |
message |
string |
String associated with the error code |
node |
string |
Name of the node that executed the task retrieved |
module |
upgrade_module |
Emiter of the task retrieved |
command |
upgrade, upgrade_custom |
Command executed by the task retrieved |
agent |
int value (id of the agent) |
Id of the agent where the task retrieved was executed |
task_id |
int value (id of the task) |
Id of the task retrieved |
create_time |
timestamp |
Creation time of the task retrieved (UTC) |
update_time |
timestamp |
Last update time of the task retrieved (UTC) |
status |
In queue, Updating, Updated, Error, Cancelled, Timeout, Legacy |
Current status of the task retrieved |
error_msg |
string |
String associated to the status when the status is Error |
Note
The legacy status is used to indicate that the upgrade is to an old version where the agent does not report the result of the task. The result of these tasks must be checked manually.
Example response:
{
"error": 0,
"data": [
{
"error": 0,
"message": "Success",
"node": "node01",
"module": "upgrade_module",
"command": "upgrade",
"agent": 5,
"task_id": 15,
"create_time": "2020/08/11 00:05:18",
"update_time": "0",
"status": "Updating"
},{
"error": 0,
"message": "Success",
"node": "node02",
"module": "upgrade_module",
"command": "upgrade",
"agent": 10,
"task_id": 16,
"create_time": "2020/08/11 00:05:30",
"update_time": "2020/08/11 00:05:52",
"status": "Error",
"error_msg": "SHA1 verification error"
}
],
"message": "Success"
}