From ad2a0675edee605bda8fe460b3656857eb050129 Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Sun, 11 Mar 2018 23:11:13 +0100 Subject: Introduce support for OXIDIZED_SSH_PASSPHRASE --- docs/Hooks.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index fab4025..080d301 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -67,6 +67,8 @@ This hook configures the repository `remote` and _push_ the code when the specif * `publickey`: publickey for repository auth. * `privatekey`: privatekey for repository auth. +It is also possible to set the environment variable `OXIDIZED_SSH_PASSPHRASE` to a passphrase if your keypair requires it. + When using groups repositories, each group must have its own `remote` in the `remote_repo` config. ``` yaml -- cgit v1.2.1 From 87600b1f5f12711afe29c408e02dbbd927e3f25d Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Mon, 12 Mar 2018 00:19:20 +0100 Subject: Lint and standardize markdown documentation --- docs/Hooks.md | 78 +++++++++++++++++++++++++++++++---------------------------- 1 file changed, 41 insertions(+), 37 deletions(-) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index fab4025..d52ee08 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -1,25 +1,30 @@ # Hooks + You can define arbitrary number of hooks that subscribe different events. The hook system is modular and different kind of hook types can be enabled. ## Configuration + Following configuration keys need to be defined for all hooks: - * `events`: which events to subscribe. Needs to be an array. See below for the list of available events. - * `type`: what hook class to use. See below for the list of available hook types. +* `events`: which events to subscribe. Needs to be an array. See below for the list of available events. +* `type`: what hook class to use. See below for the list of available hook types. ### Events - * `node_success`: triggered when configuration is succesfully pulled from a node and right before storing the configuration. - * `node_fail`: triggered after `retries` amount of failed node pulls. - * `post_store`: triggered after node configuration is stored (this is executed only when the configuration has changed). - * `nodes_done`: triggered after finished fetching all nodes. + +* `node_success`: triggered when configuration is succesfully pulled from a node and right before storing the configuration. +* `node_fail`: triggered after `retries` amount of failed node pulls. +* `post_store`: triggered after node configuration is stored (this is executed only when the configuration has changed). +* `nodes_done`: triggered after finished fetching all nodes. ## Hook type: exec + The `exec` hook type allows users to run an arbitrary shell command or a binary when triggered. The command is executed on a separate child process either in synchronous or asynchronous fashion. Non-zero exit values cause errors to be logged. STDOUT and STDERR are currently not collected. Command is executed with the following environment: -``` + +```text OX_EVENT OX_NODE_NAME OX_NODE_IP @@ -35,13 +40,13 @@ OX_REPO_NAME Exec hook recognizes following configuration keys: - * `timeout`: hard timeout for the command execution. SIGTERM will be sent to the child process after the timeout has elapsed. Default: 60 - * `async`: influences whether main thread will wait for the command execution. Set this true for long running commands so node pull is not blocked. Default: false - * `cmd`: command to run. +* `timeout`: hard timeout for the command execution. SIGTERM will be sent to the child process after the timeout has elapsed. Default: 60 +* `async`: influences whether main thread will wait for the command execution. Set this true for long running commands so node pull is not blocked. Default: false +* `cmd`: command to run. +## exec hook configuration example -## Hook configuration example -``` +```yaml hooks: name_for_example_hook1: type: exec @@ -55,21 +60,21 @@ hooks: timeout: 120 ``` -### githubrepo +### Hook type: githubrepo This hook configures the repository `remote` and _push_ the code when the specified event is triggerd. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. `githubrepo` hook recognizes following configuration keys: - * `remote_repo`: the remote repository to be pushed to. - * `username`: username for repository auth. - * `password`: password for repository auth. - * `publickey`: publickey for repository auth. - * `privatekey`: privatekey for repository auth. +* `remote_repo`: the remote repository to be pushed to. +* `username`: username for repository auth. +* `password`: password for repository auth. +* `publickey`: publickey for repository auth. +* `privatekey`: privatekey for repository auth. When using groups repositories, each group must have its own `remote` in the `remote_repo` config. -``` yaml +```yaml hooks: push_to_remote: remote_repo: @@ -78,10 +83,9 @@ hooks: firewalls: git@git.intranet:oxidized/firewalls.git ``` +## githubrepo hook configuration example -## Hook configuration example - -``` yaml +```yaml hooks: push_to_remote: type: githubrepo @@ -97,14 +101,14 @@ The `awssns` hook publishes messages to AWS SNS topics. This allows you to notif Fields sent in the message: - * `event`: Event type (e.g. `node_success`) - * `group`: Group name - * `model`: Model name (e.g. `eos`) - * `node`: Device hostname +* `event`: Event type (e.g. `node_success`) +* `group`: Group name +* `model`: Model name (e.g. `eos`) +* `node`: Device hostname -Configuration example: +## awssns hook configuration example -``` yaml +```yaml hooks: hook_script: type: awssns @@ -115,8 +119,8 @@ hooks: AWS SNS hook requires the following configuration keys: - * `region`: AWS Region name - * `topic_arn`: ASN Topic reference +* `region`: AWS Region name +* `topic_arn`: ASN Topic reference Your AWS credentials should be stored in `~/.aws/credentials`. @@ -126,13 +130,13 @@ The `slackdiff` hook posts colorized config diffs to a [Slack](http://www.slack. You will need to manually install the `slack-api` gem on your system: -``` +```shell gem install slack-api ``` -Configuration example: +## slackdiff hook configuration example -``` yaml +```yaml hooks: slack: type: slackdiff @@ -143,7 +147,7 @@ hooks: Optionally you can disable snippets and post a formatted message, for instance linking to a commit in a git repo. Named parameters `%{node}`, `%{group}`, `%{model}` and `%{commitref}` are available. -``` yaml +```yaml hooks: slack: type: slackdiff @@ -162,13 +166,13 @@ The `xmppdiff` hook posts config diffs to a [XMPP](https://en.wikipedia.org/wiki You will need to manually install the `xmpp4r` gem on your system: -``` +```shell gem install xmpp4r ``` -Configuration example: +## xmppdiff hook configuration example -``` yaml +```yaml hooks: xmpp: type: xmppdiff -- cgit v1.2.1 From 720facc6f80d2b977d73b944c81c63b6d95e768b Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Fri, 16 Mar 2018 20:31:09 +0100 Subject: improve spelling in docs --- docs/Hooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index 1d263fb..8a0a8b9 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -11,7 +11,7 @@ Following configuration keys need to be defined for all hooks: ### Events -* `node_success`: triggered when configuration is succesfully pulled from a node and right before storing the configuration. +* `node_success`: triggered when configuration is successfully pulled from a node and right before storing the configuration. * `node_fail`: triggered after `retries` amount of failed node pulls. * `post_store`: triggered after node configuration is stored (this is executed only when the configuration has changed). * `nodes_done`: triggered after finished fetching all nodes. @@ -62,7 +62,7 @@ hooks: ### Hook type: githubrepo -This hook configures the repository `remote` and _push_ the code when the specified event is triggerd. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. +This hook configures the repository `remote` and _push_ the code when the specified event is triggered. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. `githubrepo` hook recognizes following configuration keys: -- cgit v1.2.1 From 30894a5015e6ce780096bd965493913133197c14 Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Sat, 7 Apr 2018 01:49:05 +0200 Subject: extend githubrepo documentation --- docs/Hooks.md | 51 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 15 deletions(-) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index 8a0a8b9..b582a2f 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -9,7 +9,7 @@ Following configuration keys need to be defined for all hooks: * `events`: which events to subscribe. Needs to be an array. See below for the list of available events. * `type`: what hook class to use. See below for the list of available hook types. -### Events +## Events * `node_success`: triggered when configuration is successfully pulled from a node and right before storing the configuration. * `node_fail`: triggered after `retries` amount of failed node pulls. @@ -44,7 +44,7 @@ Exec hook recognizes following configuration keys: * `async`: influences whether main thread will wait for the command execution. Set this true for long running commands so node pull is not blocked. Default: false * `cmd`: command to run. -## exec hook configuration example +### exec hook configuration example ```yaml hooks: @@ -60,21 +60,29 @@ hooks: timeout: 120 ``` -### Hook type: githubrepo +## Hook type: githubrepo -This hook configures the repository `remote` and _push_ the code when the specified event is triggered. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. +The `githubrepo` hook executes a `git push` to a configured `remote_repo` when the specified event is triggered. -`githubrepo` hook recognizes following configuration keys: +Several authentication methods are supported: + +* Provide a `password` for username + password authentication +* Provide both a `publickey` and a `privatekey` for ssh key-based authentication +* Don't provide any credentials for ssh-agent authentication + +The username will be set to the relevant part of the `remote_repo` URI, with a fallback to `git`. It is also possible to provide one by setting the `username` configuration key. + +For ssh key-based authentication, it is possible to set the environment variable `OXIDIZED_SSH_PASSPHRASE` to a passphrase if the private key requires it. + +`githubrepo` hook recognizes the following configuration keys: * `remote_repo`: the remote repository to be pushed to. * `username`: username for repository auth. * `password`: password for repository auth. -* `publickey`: publickey for repository auth. -* `privatekey`: privatekey for repository auth. +* `publickey`: public key for repository auth. +* `privatekey`: private key for repository auth. -It is also possible to set the environment variable `OXIDIZED_SSH_PASSPHRASE` to a passphrase if your keypair requires it. - -When using groups repositories, each group must have its own `remote` in the `remote_repo` config. +When using groups, each group must have a unique entry in the `remote_repo` config. ```yaml hooks: @@ -85,7 +93,9 @@ hooks: firewalls: git@git.intranet:oxidized/firewalls.git ``` -## githubrepo hook configuration example +### githubrepo hook configuration example + +Authenticate with the username `git` and a password: ```yaml hooks: @@ -93,10 +103,21 @@ hooks: type: githubrepo events: [post_store] remote_repo: git@git.intranet:oxidized/test.git - username: user password: pass ``` +Authenticate with the username `git` and an ssh key: + +```yaml +hooks: + push_to_remote: + type: githubrepo + events: [post_store] + remote_repo: git@git.intranet:oxidized/test.git + publickey: /root/.ssh/id_rsa.pub + privatekey: /root/.ssh/id_rsa +``` + ## Hook type: awssns The `awssns` hook publishes messages to AWS SNS topics. This allows you to notify other systems of device configuration changes, for example a config orchestration pipeline. Multiple services can subscribe to the same AWS topic. @@ -108,7 +129,7 @@ Fields sent in the message: * `model`: Model name (e.g. `eos`) * `node`: Device hostname -## awssns hook configuration example +### awssns hook configuration example ```yaml hooks: @@ -136,7 +157,7 @@ You will need to manually install the `slack-api` gem on your system: gem install slack-api ``` -## slackdiff hook configuration example +### slackdiff hook configuration example ```yaml hooks: @@ -172,7 +193,7 @@ You will need to manually install the `xmpp4r` gem on your system: gem install xmpp4r ``` -## xmppdiff hook configuration example +### xmppdiff hook configuration example ```yaml hooks: -- cgit v1.2.1 From bb7b89f0db0c73650e0d1ac035d8441a0cb2e94f Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Sat, 7 Apr 2018 01:57:08 +0200 Subject: improve githubrepo auth example --- docs/Hooks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index b582a2f..fb80a19 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -95,7 +95,7 @@ hooks: ### githubrepo hook configuration example -Authenticate with the username `git` and a password: +Authenticate with a username and a password: ```yaml hooks: @@ -103,6 +103,7 @@ hooks: type: githubrepo events: [post_store] remote_repo: git@git.intranet:oxidized/test.git + username: user password: pass ``` -- cgit v1.2.1 From e383a573e6c11f7366ce52774e191f7272db114f Mon Sep 17 00:00:00 2001 From: Jason Ackley Date: Tue, 24 Apr 2018 10:13:49 -0500 Subject: Misc Hooks.md cleanups misc text clarity. clarify timeout is in seconds clarity the publickey/privatekey are paths - not the keys themselves. Reorder the AWS SNS example of describing the config before the example config for consistency with the rest. --- docs/Hooks.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/Hooks.md') diff --git a/docs/Hooks.md b/docs/Hooks.md index fb80a19..ff430ca 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -1,6 +1,6 @@ # Hooks -You can define arbitrary number of hooks that subscribe different events. The hook system is modular and different kind of hook types can be enabled. +You can define an arbitrary number of hooks that subscribe to different events. The hook system is modular and different kind of hook types can be enabled. ## Configuration @@ -38,10 +38,10 @@ OX_REPO_COMMITREF OX_REPO_NAME ``` -Exec hook recognizes following configuration keys: +Exec hook recognizes the following configuration keys: -* `timeout`: hard timeout for the command execution. SIGTERM will be sent to the child process after the timeout has elapsed. Default: 60 -* `async`: influences whether main thread will wait for the command execution. Set this true for long running commands so node pull is not blocked. Default: false +* `timeout`: hard timeout (in seconds) for the command execution. SIGTERM will be sent to the child process after the timeout has elapsed. Default: `60` +* `async`: Execute the command in an asynchronous fashion. The main thread by default will wait for the hook command execution to complete. Set this to `true` for long running commands so node configuration pulls are not blocked. Default: `false` * `cmd`: command to run. ### exec hook configuration example @@ -79,8 +79,8 @@ For ssh key-based authentication, it is possible to set the environment variable * `remote_repo`: the remote repository to be pushed to. * `username`: username for repository auth. * `password`: password for repository auth. -* `publickey`: public key for repository auth. -* `privatekey`: private key for repository auth. +* `publickey`: public key file path for repository auth. +* `privatekey`: private key file path for repository auth. When using groups, each group must have a unique entry in the `remote_repo` config. @@ -95,7 +95,7 @@ hooks: ### githubrepo hook configuration example -Authenticate with a username and a password: +Authenticate with a username and a password without groups in use: ```yaml hooks: @@ -130,6 +130,11 @@ Fields sent in the message: * `model`: Model name (e.g. `eos`) * `node`: Device hostname + +The AWS SNS hook requires the following configuration keys: + +* `region`: AWS Region name +* `topic_arn`: ASN Topic reference ### awssns hook configuration example ```yaml @@ -141,11 +146,6 @@ hooks: topic_arn: arn:aws:sns:us-east-1:1234567:oxidized-test-backup_events ``` -AWS SNS hook requires the following configuration keys: - -* `region`: AWS Region name -* `topic_arn`: ASN Topic reference - Your AWS credentials should be stored in `~/.aws/credentials`. ## Hook type: slackdiff -- cgit v1.2.1