CyberShell/backy-docs
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Andrew
2023-02-19 22:21:20 -06:00
parent e3f319e3c3
commit b525699fa8
237 changed files with 35813 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
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 backup -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 documentation in this section to configure it.

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

@ -0,0 +1,60 @@
---
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.
| key | description | type | required
| --- | --- | --- | --- |
| `order` | Defines the sequence of commands to execute | `[]string` | yes |
| `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.
### 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
```

90
content/config/commands.md Normal file
View File

@ -0,0 +1,90 @@
---
title: "Commands"
weight: 2
---
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
# 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 |
| `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
```
#### 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.

78
content/config/notifications.md Normal file
View File

@ -0,0 +1,78 @@
---
title: "Notifications"
weight: 2
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.
{{% notice info %}}
Type in a cmd-configs object must match one of these.
{{% /notice %}}
```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 %}}