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

[WIP] v0.7.0 almost ready to release

Browse Source
This commit is contained in:
Andrew Woodlee
2025-02-08 15:17:34 -06:00
parent 8788d473a5
commit 11ec1a98d8
34 changed files with 556 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/content/config/_index.md
View File

@ -10,6 +10,13 @@ This is the section on the config file.
To use a specific file:
```backy [command] -f /path/to/file```
You can also use a remote file:
```
backy [command] -f `s3/http source`
```
See remote resources docs for specific info.
If you leave the config path blank, the following paths will be searched in order:
1. `./backy.yml`

12
docs/content/config/command-lists.md
View File

@ -11,8 +11,16 @@ The top-level object key can be anything you want but not the same as another.
Lists can go in a separate file. Command lists should be in a separate file if:
1. key 'cmd-lists.file' is found
2. hosts.yml or hosts.yaml is found in the same directory as the backy config file
1. key 'cmd-lists.file' is specified
2. lists.yml or lists.yaml is found in the same directory as the backy config file
{{% notice info %}}
The lists file is also checked in remote resources.
The lists file is ignored under the following condition:
If a remote config file is specified (on the command-line using `-f`) and the lists file is not found in the same directory, the lists file is assumed to not exist.
{{% /notice %}}
```yaml {lineNos="true" wrap="true" title="yaml"}
test2:

21
docs/content/config/commands.md → docs/content/config/commands/_index.md
View File

@ -4,9 +4,7 @@ description: Commands are just that, commands
weight: 1
---
The yaml top-level map can be any string.
The top-level name must be unique.
### Example Config
@ -43,8 +41,8 @@ Values available for this section **(case-sensitive)**:
| --- | --- | --- | --- |
| `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`, `script`, or `package`. Runs script from local machine on remote. `Package` is the only one that can be run on local and remote hosts. | `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 |
@ -108,13 +106,14 @@ This is useful for specifying environment variables or other things so they don'
### type
May be `scriptFile` or `script`. Runs script from local machine on remote host passed to the SSH session as standard input.
The following options are available:
If `type` is `script`, `cmd` is used as the script.
If `type` is `scriptFile`, cmd must be a script file.
If `type` is `package`, there are additional fields that must be specified.
| name | description |
| --- | --- |
| script | `cmd` is used as the script |
| scriptFile | Can only be run on a host. `cmd` is read and used as the script, and `scriptEnvFile` can be used to add env variables |
| package | Run package operations. See [dedicated page](/config/packages) for configuring package commands |
| user | Run user operations. See [dedicated page](/config/user-commands) for configuring package commands |
### environment
@ -122,7 +121,7 @@ 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.
For now, the variables have to be defined in an `.env` file in the same directory that the program is run from.
If using it with host specified, the SSH server has to be configured to accept those env variables.

9
docs/content/config/packages.md → docs/content/config/commands/packages.md
View File

@ -10,8 +10,8 @@ This is dedicated to `package` commands. The command `type` field must be `packa
| --- | --- | --- | --- |
| `packageName` | The name of a package to be modified. | `string` | yes |
| `packageManager` | The name of the package manger to be used. | `string` | yes |
| `packageOperation` | The type of operation to be perform. | `string` | yes |
| `packageVersion` | The version of a package to be modified. | `string` | no |
| `packageOperation` | The type of operation to perform. | `string` | yes |
| `packageVersion` | The version of a package. | `string` | no |
#### example
@ -35,6 +35,7 @@ The following package operations are supported:
- `install`
- `remove`
- `upgrade`
- `checkVersion`
#### packageManager
@ -46,11 +47,11 @@ The following package managers are recognized:
#### package command args
You can add additional arguments using the standard `Args` key. This is useful for adding more packages.
You can add additional arguments using the standard `Args` key. This is useful for adding more packages, yet it does not work with `checkVersion`.
### Development
The PackageManager interface provides an easy to enforce functions and options. There are two interfaces, `PackageManager` and `ConfigurablePackageManager` in the directory `pkg/pkgman`. Go's import-cycle "feature" caused me to implement functional options using a third interface. `PackageManagerOption`is a function that takes an interface.
The PackageManager interface provides an easy way to enforce functions and options. There are two interfaces, `PackageManager` and `ConfigurablePackageManager` in the directory `pkg/pkgman`. Go's import-cycle "feature" caused me to implement functional options using a third interface. `PackageManagerOption`is a function that takes an interface.
#### PackageManager

62
docs/content/config/commands/user-commands.md Normal file
View File

@ -0,0 +1,62 @@
---
title: "User commands"
weight: 2
description: This is dedicated to user commands.
---
This is dedicated to `user` commands. The command `type` field must be `user`. User is a type that allows one to perform user operations. There are several additional options available when `type` is `user`:
| name | notes | type | required |
| --- | --- | --- | --- |
| `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 |
| `userHome` | The user's home directory. | `string` | no |
#### example
The following is an example of a package command:
```yaml
addUser:
name: add user backy with custom home dir
type: user
userName: backy
userHome: /opt/backy
userOperation: add
host: some-host
```
#### userOperation
The following package operations are supported:
- `add`
- `remove`
- `modify`
- `password`
- `checkIfExists`
### Development
The UserManager interface provides an way easy to add new commands. There is one interface `Usermanager` in directory `pkg/usermanager`.
#### UserManager
```go
// UserManager defines the interface for user management operations.
// All functions but one return a string for the command and any args.
type UserManager interface {
AddUser(username, homeDir, shell string, isSystem bool, groups, args []string) (string, []string)
RemoveUser(username string) (string, []string)
ModifyUser(username, homeDir, shell string, groups []string) (string, []string)
// Modify password uses chpasswd for Linux systems to build the command to change the password
// Should return a password as the last argument
// TODO: refactor when adding more systems instead of Linux
ModifyPassword(username, password string) (string, *strings.Reader, string)
UserExists(username string) (string, []string)
}
```

24
docs/content/config/hosts.md Normal file
View File

@ -0,0 +1,24 @@
---
title: "Hosts"
weight: 2
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 |
## exec host subcommand
Backy has a subcommand `exec host`. This subcommand takes the flags of `-m host1 -m host2`. For now these hosts need to be defined in the config file.

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

@ -5,6 +5,7 @@ description: >
This page tells you how to get set up Backy notifications.
---
Notifications are only configurable for command lists, as of right now.
Notifications can be sent on command list completion and failure.

17
docs/content/config/remote-resources.md Normal file
View File

@ -0,0 +1,17 @@
---
title: "Remote resources"
weight: 2
description: This is dedicated to configuring remote resources.
---
Remote resources can be used for a lot of things, including config files and scripts.
## Config file
For the main config file to be fetched remotely, pass the URL using `-f [url]`.
If using S3, you should use the s3 protocol URI: `s3://bucketName/key/path`. You will also need to set the env variable `S3_ENDPOINT` to the appropriate value. The flag `--s3-endpoint` can be used to override this value or to set this value, if not already set.
## Scripts
Scripts will be coming later.