[WIP] v0.7.0 almost ready to release
This commit is contained in:
152
docs/content/config/commands/_index.md
Normal file
152
docs/content/config/commands/_index.md
Normal file
@ -0,0 +1,152 @@
|
||||
---
|
||||
title: "Commands"
|
||||
description: Commands are just that, commands
|
||||
weight: 1
|
||||
---
|
||||
|
||||
|
||||
|
||||
### Example Config
|
||||
|
||||
```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
|
||||
# The host has to be defined in either the config file or the SSH Config files
|
||||
host: some-host
|
||||
hooks
|
||||
error:
|
||||
- some-other-command-when-failing
|
||||
success:
|
||||
- success-command
|
||||
final:
|
||||
- final-command
|
||||
backup-docker-container-script:
|
||||
cmd: /path/to/local/script
|
||||
# script file is input as stdin to SSH
|
||||
type: scriptFile # also can be script
|
||||
environment:
|
||||
- FOO=BAR
|
||||
- APP=$VAR
|
||||
```
|
||||
|
||||
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 |
|
||||
|
||||
#### cmd
|
||||
|
||||
cmd must be a valid command or script to execute.
|
||||
|
||||
#### Args
|
||||
|
||||
args must be arguments to cmd as they would be passed 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, the command will run in the specified shell.
|
||||
Make sure to escape any shell input.
|
||||
|
||||
### scriptEnvFile
|
||||
|
||||
Path to a file.
|
||||
|
||||
When type is `script` or `scriptFile` , the script is appended to this file.
|
||||
|
||||
This is useful for specifying environment variables or other things so they don't have to be included in the script.
|
||||
|
||||
### type
|
||||
|
||||
The following options are available:
|
||||
|
||||
| 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
|
||||
|
||||
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 that the program is run from.
|
||||
|
||||
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.
|
||||
|
||||
### hooks
|
||||
|
||||
Hooks are run after the command is run.
|
||||
|
||||
Errors are run if the command errors, success if it returns no error. Final hooks are run regardless of error condition.
|
||||
|
||||
Values for hooks are as follows:
|
||||
|
||||
```yaml
|
||||
command:
|
||||
hook:
|
||||
# these commands are defined elsewhere in the file
|
||||
error:
|
||||
- errcommand
|
||||
success:
|
||||
- successcommand
|
||||
final:
|
||||
- donecommand
|
||||
```
|
||||
|
||||
### packages
|
||||
|
||||
See the [dedicated page](/config/packages) for package configuration.
|
||||
79
docs/content/config/commands/packages.md
Normal file
79
docs/content/config/commands/packages.md
Normal file
@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Packages"
|
||||
weight: 2
|
||||
description: This is dedicated to package commands.
|
||||
---
|
||||
|
||||
This is dedicated to `package` commands. The command `type` field must be `package`. Package is a type that allows one to perform package operations. There are several additional options available when `type` is `package`:
|
||||
|
||||
| name | notes | type | required |
|
||||
| --- | --- | --- | --- |
|
||||
| `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 perform. | `string` | yes |
|
||||
| `packageVersion` | The version of a package. | `string` | no |
|
||||
|
||||
|
||||
#### example
|
||||
|
||||
The following is an example of a package command:
|
||||
|
||||
```yaml
|
||||
update-docker:
|
||||
type: package
|
||||
shell: zsh
|
||||
packageName: docker-ce
|
||||
packageManager: apt
|
||||
packageOperation: install
|
||||
host: debian-based-host
|
||||
```
|
||||
|
||||
#### packageOperation
|
||||
|
||||
The following package operations are supported:
|
||||
|
||||
- `install`
|
||||
- `remove`
|
||||
- `upgrade`
|
||||
- `checkVersion`
|
||||
|
||||
#### packageManager
|
||||
|
||||
The following package managers are recognized:
|
||||
|
||||
- `apt`
|
||||
- `yum`
|
||||
- `dnf`
|
||||
|
||||
#### package command args
|
||||
|
||||
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 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
|
||||
|
||||
```go
|
||||
// PackageManager is an interface used to define common package commands. This shall be implemented by every package.
|
||||
type PackageManager interface {
|
||||
Install(pkg, version string, args []string) (string, []string)
|
||||
Remove(pkg string, args []string) (string, []string)
|
||||
Upgrade(pkg, version string) (string, []string) // Upgrade a specific package
|
||||
UpgradeAll() (string, []string)
|
||||
|
||||
// Configure applies functional options to customize the package manager.
|
||||
Configure(options ...pkgcommon.PackageManagerOption)
|
||||
}
|
||||
```
|
||||
|
||||
There are a few functional options that should be implemented using the `ConfigurablePackageManager` interface:
|
||||
|
||||
```go
|
||||
// ConfigurablePackageManager defines methods for setting configuration options.
|
||||
type ConfigurablePackageManager interface {
|
||||
SetUseAuth(useAuth bool)
|
||||
SetAuthCommand(authCommand string)
|
||||
}
|
||||
```
|
||||
62
docs/content/config/commands/user-commands.md
Normal file
62
docs/content/config/commands/user-commands.md
Normal 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)
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user