119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
---
|
|
title: "Commands"
|
|
weight: 1
|
|
---
|
|
|
|
The yaml top-level map can be any string.
|
|
|
|
The top-level name must be unique.
|
|
|
|
### Example Config
|
|
|
|
```yaml
|
|
commands:
|
|
stop-docker-container:
|
|
cmd: docker
|
|
Args:
|
|
- compose
|
|
- -f /some/path/to/docker-compose.yaml
|
|
- down
|
|
# if host is not defined, command will be run locally
|
|
# The host has to be defined in either the config file or the SSH Config files
|
|
host: some-host
|
|
backup-docker-container-script:
|
|
cmd: /path/to/local/script
|
|
# script file is input as stdin to SSH
|
|
type: scriptFile # also can be script
|
|
environment:
|
|
- FOO=BAR
|
|
- APP=$VAR
|
|
```
|
|
|
|
Values available for this section:
|
|
|
|
| name | notes | type | required
|
|
| --- | --- | --- | --- |
|
|
| `cmd` | Defines the command to execute | `string` | yes |
|
|
| `args` | Defines the arguments to the command | `[]string` | no |
|
|
| `environment` | Defines evironment variables for the command | `[]string` | no |
|
|
| `type` | May be `scriptFile` or `script`. Runs script from local machine on remote. Only applicable when `host` is defined. | `string` | no |
|
|
| `getOutput` | Command(s) output is in the notification(s) | `bool` | no |
|
|
| `host` | If not specified, the command will execute locally. | `string` | no |
|
|
| `scriptEnvFile` | When type is `scriptFile`, the script is appended to this file. | `string` | no |
|
|
| `shell` | Only applicable when host is not specified | `string` | no |
|
|
|
|
#### cmd
|
|
|
|
cmd must be a valid command or script to execute.
|
|
|
|
#### args
|
|
|
|
args must be arguments to cmd as they would be on the command-line:
|
|
|
|
```sh
|
|
cmd [arg1 arg2 ...]
|
|
```
|
|
|
|
Define them in an array:
|
|
|
|
```yaml
|
|
args:
|
|
- arg1
|
|
- arg2
|
|
- arg3
|
|
```
|
|
|
|
### getOutput
|
|
|
|
Get command output when a notification is sent.
|
|
|
|
Is not required. Can be `true` or `false`.
|
|
|
|
#### host
|
|
|
|
{{% notice info %}}
|
|
If any `host` is not defined or left blank, the command will run on the local machine.
|
|
{{% /notice %}}
|
|
|
|
Host may or may not be defined in the `hosts` section.
|
|
|
|
{{% notice info %}}
|
|
If any `host` from the commands section does not match any object in the `hosts` section, the `Host` is assumed to be this value. This value will be used to search in the default SSH config files.
|
|
|
|
For example, say that I have a host defined in my SSH config with the `Host` defined as `web-prod`.
|
|
If I assign a value to host as `host: web-prod` and don't specify this value in the `hosts` object, web-prod will be used as the `Host` in searching the SSH config files.
|
|
{{% /notice %}}
|
|
|
|
### shell
|
|
|
|
If shell is defined and host is NOT defined, the command will run in the specified shell.
|
|
Make sure to escape any shell input.
|
|
|
|
### scriptEnvFile
|
|
|
|
Path to a file.
|
|
|
|
When type is `scriptFile`, the script is appended to this file.
|
|
|
|
This is useful for specifiing environment variables or other things so they don't have to be included in the script.
|
|
|
|
### type
|
|
|
|
May be `scriptFile` or `script`. Runs script from local machine on remote host passed to the SSH session as standard input.
|
|
|
|
If `type` is `script`, `cmd` is used as the script.
|
|
|
|
If `type` is `scriptFile`, cmd must be a file path.
|
|
|
|
### environment
|
|
|
|
The environment variables support expansion:
|
|
|
|
- using escaped values `$VAR` or `${VAR}`
|
|
|
|
For now, the variables have to be defined in an `.env` file in the same directory as the config file.
|
|
|
|
If using it with host specified, the SSH server has to be configured to accept those env variables.
|
|
|
|
If the command is run locally, the OS's environment is added.
|