command_execution_once

Execute a command only once on a node.

⚙️ Compatible targets: Linux

Parameters

Name	Documentation
command	Command to run. This parameter is required.
ok_codes	List of codes that produce a repaired status separated with commas (ex: 1,2,5). Defaults to 0. This parameter is optional.
until	Try to execute the command until a particular state: 'ok', 'any' (defaults to 'any'). Choices: `any` `ok` This parameter is optional.
unique_id	To identify the action without losing track if the command changes. Defaults to the command if you don't need it. This parameter is optional.

Outcome conditions

You need to replace ${command} with its actual canonified value.

✅ Ok: command_execution_once_${command}_ok
- ☑️ Already compliant: command_execution_once_${command}_kept
- 🟨 Repaired: command_execution_once_${command}_repaired
❌ Error: command_execution_once_${command}_error

Example

method: command_execution_once
params:
  command: VALUE
  until: any
  ok_codes: OPTIONAL_VALUE
  unique_id: OPTIONAL_VALUE

Documentation

This method is useful for specific commands that should only be executed once per node.

If you can spot a condition for the command execution by testing the state of its target, it is better to use the condition_from_command method to test the state coupled with the command_execution_result method to run the command if necessary.

In case of reinstallation or factory-reset of the Rudder agent, this method will no longer detect if a command has already been executed.

The method will:

Define the command_execution_once_${command}_kept condition and do nothing if a command_execution_once has already been executed on this machine with the same Unique id.

Execute the command if it is the first occurrence and:

If the parameter Until is *any*, it will consider the command as executed on the machine and define either:
- command_execution_once_${command}_repaired if the return code is in ok_codes,
- command_execution_once_${command}_error otherwise.
If the parameter Until is ok and:
- If the return code is in the Ok codes list, define the command_execution_once_${command}_repaired condition
- If the return code is not in Ok codes it define the command_execution_once_${command}_error condition and retry at next agent run.

If an exit code is not in the list it will lead to an error status. If you want "0" to be a success you have to list it in the Ok codes list

Example:

If you use:

    command_execution_once("command -a -t", "0", "ok", "my_program_setup")

It will retry to run command -a -t until it returns "0". Then it will not execute it again.