CyberShell/backy
1
1
Fork 0
Code Issues 5 Pull Requests Packages Projects 1 Releases 18 Wiki Activity

added external directives to Notifications, change case of keys in host, and update docs

Browse Source
This commit is contained in:
Andrew Woodlee 2025-03-08 00:23:08 -06:00
parent 65c46a1e26
commit d8453d1fb0
12 changed files with 100 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.changes/unreleased/Changed-20250307-231946.yaml Normal file
View File

@ -0,0 +1,3 @@
kind: Changed
body: 'Host: changes to case of some keys'
time: 2025-03-07T23:19:46.086408374-06:00

3
.changes/unreleased/Changed-20250308-001824.yaml Normal file
View File

@ -0,0 +1,3 @@
kind: Changed
body: 'Notifications: added external directive to sensitive keys'
time: 2025-03-08T00:18:24.976897007-06:00

2
docs/content/cli/exec.md
View File

@ -15,5 +15,5 @@ The `exec` subcommand can do some things that the configuration file can't do ye
The commands have to be defined in the config file. The hosts need to at least be in the ssh_config(5) file.
```sh
backy exec host [--commands=command1 -commands=command2 ... | -c command1 -c command2 ...] [--hosts=host1 --hosts=hosts2 ... | -m host1 -c host2 ...] [flags]
backy exec host [--commands=command1 -commands=command2 ... | -c command1 -c command2 ...] [--hosts=host1 --hosts=hosts2 ... | -m host1 -m host2 ...] [flags]
```

29
docs/content/cli/list.md Normal file
View File

@ -0,0 +1,29 @@
---
title: List
---
List commands, lists, or hosts defined in config file
Usage:
```
backy list [command]
```
Available Commands:
cmds List commands defined in config file.
lists List lists defined in config file.
Flags:
```
-h, --help help for list
```
Global Flags:
```
--cmdStdOut Pass to print command output to stdout
-f, --config string config file to read from
--log-file string log file to write to
--s3-endpoint string Sets the S3 endpoint used for config file fetching. Overrides S3_ENDPOINT env variable.
-v, --verbose Sets verbose level
```

22
docs/content/config/commands/_index.md
View File

@ -12,17 +12,17 @@ weight: 1
Values available for this section **(case-sensitive)**:
| name | notes | type | required
| --- | --- | --- | --- |
| `cmd` | Defines the command to execute | `string` | yes |
| `Args` | Defines the arguments to the command | `[]string` | no |
| `environment` | Defines environment variables for the command | `[]string` | no |
| `type` | See documentation further down the page. Additional fields may be required. | `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` or `script`, this file is prepended to the input. | `string` | no |
| `shell` | Run the command in the shell | `string` | no |
| `hooks` | Hooks are used at the end of the individual command. Must have at least `error`, `success`, or `final`. | `map[string][]string` | no |
| name | notes | type | required | External directive support |
| ----------------| ------------------------------------------------------------------------------------------------------- | --------------------- | -------- |----------------------------|
| `cmd` | Defines the command to execute | `string` | yes | No |
| `Args` | Defines the arguments to the command | `[]string` | no | No |
| `environment` | Defines environment variables for the command | `[]string` | no | No |
| `type` | See documentation further down the page. Additional fields may be required. | `string` | no | No |
| `getOutput` | Command(s) output is in the notification(s) | `bool` | no | No |
| `host` | If not specified, the command will execute locally. | `string` | no | No |
| `scriptEnvFile` | When type is `scriptFile` or `script`, this file is prepended to the input. | `string` | no | No |
| `shell` | Run the command in the shell | `string` | no | No |
| `hooks` | Hooks are used at the end of the individual command. Must have at least `error`, `success`, or `final`. | `map[string][]string` | no | No |
#### cmd

8
docs/content/config/commands/user-commands.md
View File

@ -10,10 +10,12 @@ This is dedicated to `user` commands. The command `type` field must be `user`. U
| --- | --- | --- | --- |
| `userName` | The name of a user to be configured. | `string` | yes |
| `userOperation` | The type of operation to perform. | `string` | yes |
| `userID` | The user ID to use. | `string` | yes |
| `userGroups` | The groups the user should be added to. | `[]string` | yes |
| `userShell` | The shell for the user. | `string` | yes |
| `userID` | The user ID to use. | `string` | no |
| `userGroups` | The groups the user should be added to. | `[]string` | no |
| `userSshPubKeys` | The keys to add to the user's authorized keys. | `[]string` | no |
| `userShell` | The shell for the user. | `string` | no |
| `userHome` | The user's home directory. | `string` | no |
| `userPassword` | The new password value when using the `password` operation. Can be specified by using external directive. | `string` | no |
#### example

15
docs/content/config/directives.md Normal file
View File

@ -0,0 +1,15 @@
---
title: "External Directives"
weight: 2
description: How to set up external directives.
---
External directives are for including data that should not be in the config file. The following directives are supported:
- `%{file:path/to/file}%`
- `%{env:ENV_VAR}%`
- `%{vault:vault-key}%`
See the docs of each command if the field is supported.
If the file path does not begin with a `/`, the config file's directory will be used as the starting point.

26
docs/content/config/hosts.md
View File

@ -5,19 +5,19 @@ description: >
This page tells you how to use hosts.
---
| Key | Description | Type | Required |
|----------------------|---------------------------------------------------------------|----------|----------|
| `OS` | Operating system of the host (used for package commands) | `string` | no |
| `config` | Path to the SSH config file | `string` | no |
| `host` | Specifies the `Host` ssh_config(5) directive | `string` | yes |
| `hostname` | Hostname of the host | `string` | no |
| `knownhostsfile` | Path to the known hosts file | `string` | no |
| `port` | Port number to connect to | `uint16` | no |
| `proxyjump` | Proxy jump hosts, comma-separated | `string` | no |
| `password` | Password for SSH authentication | `string` | no |
| `privatekeypath` | Path to the private key file | `string` | no |
| `privatekeypassword` | Password for the private key file | `string` | no |
| `user` | Username for SSH authentication | `string` | no |
| Key | Description | Type | Required | External directive support |
|----------------------|---------------------------------------------------------------|----------|----------|----------------------------|
| `OS` | Operating system of the host (used for package commands) | `string` | no | No |
| `config` | Path to the SSH config file | `string` | no | No |
| `host` | Specifies the `Host` ssh_config(5) directive | `string` | yes | No |
| `hostname` | Hostname of the host | `string` | no | No |
| `knownHostsFile` | Path to the known hosts file | `string` | no | No |
| `port` | Port number to connect to | `uint16` | no | No |
| `proxyjump` | Proxy jump hosts, comma-separated | `string` | no | No |
| `password` | Password for SSH authentication | `string` | no | No |
| `privateKeyPath` | Path to the private key file | `string` | no | No |
| `privateKeyPassword` | Password for the private key file | `string` | no | Yes |
| `user` | Username for SSH authentication | `string` | no | No |
## exec host subcommand

28
docs/content/config/notifications.md
View File

@ -39,23 +39,23 @@ There must be a section with an id (eg. `mail.test-svr`) following one of these
### 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`
| key | description | type | External directive support |
| --- | --- | --- | --- |
| `host` | Specifies the SMTP host to connect to | `string` | no
| `port` | Specifies the SMTP port | `uint16` | no
| `senderaddress` | Address from which to send mail | `string` | no
| `to` | Recipients to send emails to | `[]string` | no
| `username` | SMTP username | `string` | no
| `password` | SMTP password | `string` | yes
### 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`
| key | description | type | External directive support |
| --- | --- | ---| ---- |
| `home-server` | Specifies the Matrix server connect to | `string` | no
| `room-id` | Specifies the room ID of the room to send messages to | `string` | no
| `access-token` | Matrix access token | `string` | yes
| `user-id` | Matrix user ID | `string` | no
To get your access token (assumes you are using [Element](https://element.io/)) :

2
docs/content/examples/backy.yaml
View File

@ -71,7 +71,7 @@ hosts:
hostname: some-hostname
config: ~/.ssh/config
user: user
privatekeypath: /path/to/private/key
privateKeyPath: /path/to/private/key
port: 22
# can also be env:VAR
password: file:/path/to/file

2
pkg/backy/notification.go
View File

@ -58,6 +58,7 @@ func (opts *ConfigOpts) SetupNotify() {
opts.Logger.Info().Err(fmt.Errorf("error: ID %s not found in mail object", confId)).Str("list", confName).Send()
continue
}
conf.Password = getExternalConfigDirectiveValue(conf.Password, opts)
mailConf := setupMail(conf)
services = append(services, mailConf)
case "matrix":
@ -66,6 +67,7 @@ func (opts *ConfigOpts) SetupNotify() {
opts.Logger.Info().Err(fmt.Errorf("error: ID %s not found in matrix object", confId)).Str("list", confName).Send()
continue
}
conf.AccessToken = getExternalConfigDirectiveValue(conf.AccessToken, opts)
mtrxConf, mtrxErr := setupMatrix(conf)
if mtrxErr != nil {
opts.Logger.Info().Str("list", confName).Err(fmt.Errorf("error: configuring matrix id %s failed during setup: %w", id, mtrxErr))

6
pkg/backy/types.go
View File

@ -26,15 +26,15 @@ type (
ConfigFilePath string `yaml:"config,omitempty"`
Host string `yaml:"host,omitempty"`
HostName string `yaml:"hostname,omitempty"`
KnownHostsFile string `yaml:"knownhostsfile,omitempty"`
KnownHostsFile string `yaml:"knownHostsFile,omitempty"`
ClientConfig *ssh.ClientConfig
SSHConfigFile *sshConfigFile
SshClient *ssh.Client
Port uint16 `yaml:"port,omitempty"`
ProxyJump string `yaml:"proxyjump,omitempty"`
Password string `yaml:"password,omitempty"`
PrivateKeyPath string `yaml:"privatekeypath,omitempty"`
PrivateKeyPassword string `yaml:"privatekeypassword,omitempty"`
PrivateKeyPath string `yaml:"privateKeyPath,omitempty"`
PrivateKeyPassword string `yaml:"privateKeyPassword,omitempty"`
useDefaultConfig bool
User string `yaml:"user,omitempty"`
isProxyHost bool