CyberShell/backy
1
1
Fork 0
Code Issues 10 Pull Requests Packages Projects 1 Releases 20 Wiki Activity

v0.3.0

Browse Source 
* Getting environment variables and passwords from Vault (not tested
yet)
* Vault configuration to config (not tested yet)
* Ability to run scripts from file on local machine on the remote host
* Ability to get ouput in the notification of a list for individual
commands or all commands
* Make SSH connections close after all commands have been run; reuse
previous connections if needed
This commit is contained in:
Andrew Woodlee
2023-07-01 21:46:54 -05:00
parent 5e7c52997c
commit 4b382bddd9
831 changed files with 83782 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/content/config/_index.md Normal file
View File

@ -0,0 +1,22 @@
---
title: "Configuring Backy"
weight: 3
description: >
This page tells you how to configure Backy.
---
This is the section on the config file.
To use a specific file:
```backy [command] -f /path/to/file```
If you leave the config path blank, the following paths will be searched in order:
- `./backy.yml`
- `./backy.yaml`
- `~/.config/backy.yml`
- `~/.config/backy.yaml`
Create a file at `~/.config/backy.yml`.
See the rest of the documentation in this section to configure it.

85
docs/content/config/command-lists.md Normal file
View File

@ -0,0 +1,85 @@
---
title: "Command Lists"
weight: 2
description: >
This page tells you how to get started with Backy.
---
Command lists are for executing commands in sequence and getting notifications from them.
The top-level object key can be anything you want but not the same as another.
```yaml
test2:
name: test2
order:
- test
- test2
notifications:
- prod-email
- matrix
cron: "0 * * * * *"
```
| key | description | type | required
| --- | --- | --- | --- |
| `order` | Defines the sequence of commands to execute | `[]string` | yes |
| `getOutput` | Command(s) output is in the notification(s) | `bool` | no |
| `notifications` | The notification IDs to use on success and failure | `[]string` | no |
| `name` | Optional name of the list | `string` | no |
| `cron` | Time at which to schedule the list. | `string` | no |
### Order
The order is an array of commands to execute in order. Each command must be defined.
```yaml
order:
- cmd-1
- cmd-2
```
### getOutput
Get command output when a notification is sent.
Is not required. Can be `true` or `false`.
### Notifications
An array of notification IDs to use on success and failure. Must match any of the `notifications` object map keys.
### Name
Name is optional for logging. If name is not defined, name will be the object's map key.
### Cron mode
Backy also has a cron mode, so one can run `backy cron` and start a process that schedules jobs to run at times defined in the configuration file.
Adding `cron: 0 0 1 * * *` to a `cmd-configs` object will schedule the list at 1 in the morning. See [https://crontab.guru/](https://crontab.guru/) for reference.
{{% notice tip %}}
Note: Backy uses the second field of cron, so add anything except * to the beginning of a regular cron expression.
{{% /notice %}}
```yaml
cmd-configs:
  cmds-to-run: # this can be any name you want
    # all commands have to be defined
    order:
      - stop-docker-container
      - backup-docker-container-script
      - shell-cmd
      - hostname
    notifications:
      - matrix
    name: backup-some-server
    cron: "0 0 1 * * *"
  hostname:
    name: hostname
    order:
      - hostname
    notifications:
    - prod-email
```

97
docs/content/config/commands.md Normal file
View File

@ -0,0 +1,97 @@
---
title: "Commands"
weight: 1
---
The yaml top-level map can be any string.
The top-level name must be unique.
```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
host: some-host
backup-docker-container-script:
cmd: /path/to/script/on/some-host
# The host has to be defined in either the config file or the SSH Config files
host: some-host
environment:
- FOO=BAR
- APP=$VAR
```
Values available for this section:
| name | description | 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 |
| `getOutput` | Command(s) output is in the notification(s) | `bool` | no |
| `host` | If not specified, the command will execute locally. | `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.
### 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.

74
docs/content/config/notifications.md Normal file
View File

@ -0,0 +1,74 @@
---
title: "Notifications"
weight: 3
description: >
This page tells you how to get set up Backy notifications.
---
Notifications can be sent on command list completion and failure.
The supported platforms for notifications are email (SMTP) and [Matrix](https://matrix.org/).
Notifications are defined by type. The top-level object will be the id, and the `type` is required.
```yaml
notifications:
prod-email:
type: mail
host: yourhost.tld
port: 587
senderaddress: email@domain.tld
to:
- admin@domain.tld
username: smtp-username@domain.tld
password: your-password-here
matrix:
type: matrix
home-server: your-home-server.tld
room-id: room-id
access-token: your-access-token
user-id: your-user-id
```
Types recognized are `type: mail` and `type: matrix`
The type's object and its keys are listed below.
### type: mail
| key | description | type
| --- | --- | ---
| `host` | Specifies the SMTP host to connect to | `string`
| `port` | Specifies the SMTP port | `uint16`
| `senderaddress` | Address from which to send mail | `string`
| `to` | Recipients to send emails to | `[]string`
| `username` | SMTP username | `string`
| `password` | SMTP password | `string`
### type: matrix
| key | description | type
| --- | --- | ---
| `home-server` | Specifies the Matrix server connect to | `string`
| `room-id` | Specifies the room ID of the room to send messages to | `string`
| `access-token` | Matrix access token | `string`
| `user-id` | Matrix user ID | `string`
To get your access token (assumes you are using [Element](https://element.io/)) :
1. Log in to the account you want to get the access token for. Click on the name in the top left corner, then "Settings".
2. Click the "Help & About" tab (left side of the dialog).
3. Scroll to the bottom and click on `<click to reveal>` part of Access Token.
4. Copy your access token to a safe place.
To get the room ID:
1. On Element or a similar client, navigate to the room.
2. Navigate to the settings from the top menu.
3. Click on Advanced, the room ID is there.
{{% notice info %}}
Make sure to quote the room ID, as [YAML spec defines tags using `!`](https://yaml.org/spec/1.2.2/#3212-tags).
{{% /notice %}}

26
docs/content/config/vault.md Normal file
View File

@ -0,0 +1,26 @@
---
title: "Vault"
weight: 4
---
[Vault](https://www.vaultproject.io/) is a tool for storing secrets and other data securely.
Vault config can be used by prefixing `vault:` in front of a password or ENV var.
This is the object in the config file:
```yaml
vault:
token: hvs.tXqcASvTP8wg92f7riyvGyuf
address: http://127.0.0.1:8200
enabled: false
keys:
- name: mongourl
mountpath: secret
path: mongo/url
type: # KVv1 or KVv2
- name:
path:
type:
mountpath:
```