Run a command on a machine
Run a command on a machine without opening a shell, and get its output and its exit code back. It runs as root, so it can install packages, restart services and change anything on the machine.
Run it
Section titled “Run it”Open the machine, go to its Commands tab and choose Run a command. Enter the command, and optionally a working directory, a timeout in seconds and environment variables. The dialog follows the command until it finishes and shows its output. Close and leave it running closes the dialog without stopping the command.
Everything after -- is the program and its arguments:
deployport machinery commands run mach_kxpkzlq4qf -- docker psThe command waits for the result, prints the program’s output on stdout and stderr, and exits with the program’s own exit code, so it works in a script or a CI job.
There is no shell around the command, so pipes, redirection and cd need one spelled out:
deployport machinery commands run mach_kxpkzlq4qf -- sh -c 'docker ps | wc -l'If everything worked, the output is the program’s own and the run ends as succeeded. deployport machinery commands list <machine-id> shows the run and how it ended.
Run a script
Section titled “Run a script”Pass the script’s text to sh -c:
deployport machinery commands run mach_kxpkzlq4qf -- sh -c "$(cat deploy.sh)"The command gets no standard input, so a script that waits for an answer reads nothing and goes on. To run as the login user instead of root, put sudo -u deployport in front of the program.
Options
Section titled “Options”| Option | What it does |
|---|---|
--workdir <dir> | The directory to run in, which takes the place of cd |
--env NAME=VALUE | Adds a variable to the command’s environment, and can be repeated |
--timeout <duration> | Stops the command after this long, 5 minutes by default and 1 hour at most |
--no-wait | Queues the command and prints it without waiting for the result |
Exit codes
Section titled “Exit codes”The CLI exits with the program’s own code when it is between 1 and 255. Its own codes are:
| Code | Meaning |
|---|---|
0 | The command succeeded |
121 | The CLI stopped waiting before the result arrived |
122 | The command was cancelled |
123 | The machine refused to run it, for example because the program does not exist |
124 | The command reached its timeout and was stopped |
125 | The command never reached the machine |
130 | You pressed Ctrl+C, and the command keeps running on the machine |
When the machine is not running
Section titled “When the machine is not running”A command for a stopped or offline machine waits in the machine’s queue for up to an hour and runs when the machine comes back. The CLI stops waiting after 30 seconds, exits with 125, and prints how to read the result later. Start the machine and let it come online before you run a command you need to wait for.
Read results later
Section titled “Read results later”deployport machinery commands list mach_kxpkzlq4qfdeployport machinery commands get <command-id>A command and its output stay readable for about an hour after it finishes. The machine’s activity log keeps a line for each run, with the command, who ran it, how it ended and its exit code, for 90 days. It does not keep the output or the environment.
Limits
Section titled “Limits”- A machine runs up to 5 commands at once, and up to 8 more can wait in its queue.
- Each output stream keeps up to 64 KiB from the machine, and the stored result keeps its first 16 KiB and its last 8 KiB.
- Running the same command twice runs it twice.
Permissions
Section titled “Permissions”| Action | What it allows |
|---|---|
machinery:RunCommand | Run a command as root on a machine |
machinery:ListCommands | Read a machine’s commands and their output, which waiting for a result needs too |
machinery:CancelCommand | Cancel a command that has not started yet |
A command that has already started cannot be cancelled. It runs until it finishes or reaches its timeout.
Commands and setup steps
Section titled “Commands and setup steps”A setup step runs once, on each machine created after it is added, from the account’s setup settings. A command runs once, now, on a machine you already have, and nothing is stored. Set what every machine inherits covers the settings, setup included.