From d8453d1fb024e5ef98ae31238c5259b2837c398e Mon Sep 17 00:00:00 2001 From: Andrew Woodlee Date: Sat, 8 Mar 2025 00:23:08 -0600 Subject: [PATCH] added external directives to Notifications, change case of keys in host, and update docs --- .../unreleased/Changed-20250307-231946.yaml | 3 ++ .../unreleased/Changed-20250308-001824.yaml | 3 ++ docs/content/cli/exec.md | 2 +- docs/content/cli/list.md | 29 +++++++++++++++++++ docs/content/config/commands/_index.md | 22 +++++++------- docs/content/config/commands/user-commands.md | 8 +++-- docs/content/config/directives.md | 15 ++++++++++ docs/content/config/hosts.md | 26 ++++++++--------- docs/content/config/notifications.md | 28 +++++++++--------- docs/content/examples/backy.yaml | 2 +- pkg/backy/notification.go | 2 ++ pkg/backy/types.go | 6 ++-- 12 files changed, 100 insertions(+), 46 deletions(-) create mode 100644 .changes/unreleased/Changed-20250307-231946.yaml create mode 100644 .changes/unreleased/Changed-20250308-001824.yaml create mode 100644 docs/content/cli/list.md create mode 100644 docs/content/config/directives.md diff --git a/.changes/unreleased/Changed-20250307-231946.yaml b/.changes/unreleased/Changed-20250307-231946.yaml new file mode 100644 index 0000000..9170694 --- /dev/null +++ b/.changes/unreleased/Changed-20250307-231946.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: 'Host: changes to case of some keys' +time: 2025-03-07T23:19:46.086408374-06:00 diff --git a/.changes/unreleased/Changed-20250308-001824.yaml b/.changes/unreleased/Changed-20250308-001824.yaml new file mode 100644 index 0000000..f757d92 --- /dev/null +++ b/.changes/unreleased/Changed-20250308-001824.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: 'Notifications: added external directive to sensitive keys' +time: 2025-03-08T00:18:24.976897007-06:00 diff --git a/docs/content/cli/exec.md b/docs/content/cli/exec.md index c29c359..fff7afd 100644 --- a/docs/content/cli/exec.md +++ b/docs/content/cli/exec.md @@ -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] ``` diff --git a/docs/content/cli/list.md b/docs/content/cli/list.md new file mode 100644 index 0000000..ce4fbad --- /dev/null +++ b/docs/content/cli/list.md @@ -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 +``` \ No newline at end of file diff --git a/docs/content/config/commands/_index.md b/docs/content/config/commands/_index.md index 7658ee0..4be0055 100644 --- a/docs/content/config/commands/_index.md +++ b/docs/content/config/commands/_index.md @@ -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 diff --git a/docs/content/config/commands/user-commands.md b/docs/content/config/commands/user-commands.md index 91f649e..ea4cc3d 100644 --- a/docs/content/config/commands/user-commands.md +++ b/docs/content/config/commands/user-commands.md @@ -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 diff --git a/docs/content/config/directives.md b/docs/content/config/directives.md new file mode 100644 index 0000000..97422c8 --- /dev/null +++ b/docs/content/config/directives.md @@ -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. \ No newline at end of file diff --git a/docs/content/config/hosts.md b/docs/content/config/hosts.md index 47096db..8a903aa 100644 --- a/docs/content/config/hosts.md +++ b/docs/content/config/hosts.md @@ -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 diff --git a/docs/content/config/notifications.md b/docs/content/config/notifications.md index 23dd116..5175f0a 100644 --- a/docs/content/config/notifications.md +++ b/docs/content/config/notifications.md @@ -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/)) : diff --git a/docs/content/examples/backy.yaml b/docs/content/examples/backy.yaml index 17046dd..0adc42b 100644 --- a/docs/content/examples/backy.yaml +++ b/docs/content/examples/backy.yaml @@ -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 diff --git a/pkg/backy/notification.go b/pkg/backy/notification.go index 21cf509..eb1e708 100644 --- a/pkg/backy/notification.go +++ b/pkg/backy/notification.go @@ -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)) diff --git a/pkg/backy/types.go b/pkg/backy/types.go index 6289074..dca6db6 100644 --- a/pkg/backy/types.go +++ b/pkg/backy/types.go @@ -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