Skip to content

Latest commit

 

History

History
373 lines (285 loc) · 12.1 KB

Hooks.md

File metadata and controls

373 lines (285 loc) · 12.1 KB
Raw

Hooks

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.

  1. Events
  2. Hook types

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

  • 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.

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:

OX_EVENT
OX_NODE_NAME
OX_NODE_IP
OX_NODE_FROM
OX_NODE_MSG
OX_NODE_GROUP
OX_NODE_MODEL
OX_JOB_STATUS
OX_JOB_TIME
OX_REPO_COMMITREF
OX_REPO_NAME
OX_ERR_TYPE
OX_ERR_REASON

Exec hook recognizes the following configuration keys:

  • 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

hooks:
  name_for_example_hook1:
    type: exec
    events: [node_success]
    cmd: 'echo "Node success $OX_NODE_NAME" >> /tmp/ox_node_success.log'
  name_for_example_hook2:
    type: exec
    events: [post_store, node_fail]
    cmd: 'echo "Doing long running stuff for $OX_NODE_NAME" >> /tmp/ox_node_stuff.log; sleep 60'
    async: true
    timeout: 120

Exec Hook configuration example to send mail

To send mail you need the package msmtp (It is pre-installed with the docker container)

You then need to update the ~/.msmtprc file to contain your SMTP credentials like this:

Note: In the docker container the file is in /home/oxidized/.config/oxidized/.msmtprc so you can create the file if it doesn't exist in your oxidized config folder.

# Default settings
defaults
auth    on
tls    on
# Outlook SMTP
account    mainaccount
host       smtp.office365.com
port       587
from       [email protected]
user       [email protected]
password   edit-password

account default : mainaccount

For non docker users this file should have the 600 permission, using: chmod 600 .msmtprc and the owner of the file should be the owner of oxidized chown oxidized:oxidized .msmtprc

Then, you can configure Hooks to send mail like this:

hooks:
  send_mail_hook:
    type: exec
    events: [node_fail]
    cmd: '/usr/bin/echo -e "Subject: [Oxidized] Error on node $OX_NODE_NAME \n\nThe device $OX_NODE_NAME has not been backed-up, reason: \n\n$OX_EVENT: $OX_ERR_REASON" | msmtp [email protected]'

Hook type: githubrepo

Note: You must not use the same name as any local repo configured under output. Make sure your 'git' output has a unique name that does not match your remote_repo.

The githubrepo hook executes a git push to a configured remote_repo when the specified event is triggered.

Several authentication methods are supported:

  • Provide a password for username + password authentication
  • Provide both a publickey and a privatekey for ssh key-based authentication
  • Provide only a privatekey (public key filename is assumed to be privatekey + ".pub"
  • 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: public key file path for repository auth. (optional)
  • privatekey: private key file path for repository auth.
    • NOTE: this key needs to be in the legacy PEM format, not the newer OpenSSL format #1877, #2324
      • To convert a key beginning with BEGIN OPENSSH PRIVATE KEY to the legacy PEM format, run this command: ssh-keygen -p -m PEM -f $MY_KEY_HERE

When using groups, remote_repo must be a dictionary of groups that the hook should apply to. If a group is missing from the dictionary, no action will be taken.

The dictionary entry can either be a url alone:

hooks:
  push_to_remote:
    remote_repo:
      routers: [email protected]:oxidized/routers.git
      switches: [email protected]:oxidized/switches.git
      firewalls: [email protected]:oxidized/firewalls.git

... or it can be a dictionary with url and privatekey specified:

hooks:
  push_to_remote:
    remote_repo:
      routers:
        url: [email protected]:oxidized/routers.git
        privatekey: /root/.ssh/id_rsa_routers
      switches:
        url: [email protected]:oxidized/switches.git
        privatekey: /root/.ssh/id_rsa_switches
      firewalls:
        url: [email protected]:oxidized/firewalls.git
        privatekey: /root/.ssh/id_rsa_firewalls

Both forms can be mixed and matched.

githubrepo hook configuration example

Authenticate with a username and a password without groups in use:

hooks:
  push_to_remote:
    type: githubrepo
    events: [post_store]
    remote_repo: [email protected]:oxidized/test.git
    username: user
    password: pass

Authenticate with the username git and an ssh key:

hooks:
  push_to_remote:
    type: githubrepo
    events: [post_store]
    remote_repo: [email protected]:oxidized/test.git
    publickey: /root/.ssh/id_rsa.pub
    privatekey: /root/.ssh/id_rsa

Custom branch name

Githubrepo will use the branch name used in the git output as a remote branch name. When creating the git repository for the first time, Oxidized uses the default branch name configured in git with git config --global init.defaultBranch <Name>. The default is master.

If you need to rename the branch name after Oxidized has created it, you may do it manually. Be aware that you may break things. Make backups and do not complain if something goes wrong!

  1. Stop oxidized (no one should access the git repository while doing the following steps)
  2. Make a backup of your oxidized data, especially the git repository
  3. Change directory to your oxidized git repository (as configured in oxidized configuration file)
  4. Inspect the current branches with git branch -avv
  5. Rename the default branch with git branch -m <NewName>
  6. Remove the reference to the old remote branch with git branch -r -d origin/<OldName>
  7. Inspect the change with git branch -avv
  8. Restart oxidized - you're done!

Note that you will also have to clean your remote git repository.

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.

Fields sent in the message:

  • event: Event type (e.g. node_success)
  • group: Group name
  • 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

hooks:
  hook_script:
    type: awssns
    events: [node_fail,node_success,post_store]
    region: us-east-1
    topic_arn: arn:aws:sns:us-east-1:1234567:oxidized-test-backup_events

Your AWS credentials should be stored in ~/.aws/credentials.

Hook type: slackdiff

The slackdiff hook posts colorized config diffs to a Slack channel of your choice. It only triggers for post_store events.

You will need to manually install the slack-ruby-client gem on your system:

gem install slack-ruby-client

slackdiff hook configuration example

hooks:
  slack:
    type: slackdiff
    events: [post_store]
    token: SLACK_BOT_TOKEN
    channel: "#network-changes"

The token parameter is a Slack API token that can be generated following this tutorial. Until Slack stops supporting them, legacy tokens can also be used.

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.

hooks:
  slack:
    type: slackdiff
    events: [post_store]
    token: SLACK_BOT_TOKEN
    channel: "#network-changes"
    diff: false
    message: "%{node} %{group} %{model} updated https://git.intranet/network-changes/commit/%{commitref}"

Note the channel name must be in quotes.

A proxy can optionally be specified if needed to reach the Slack API endpoint.

hooks:
  slack:
    type: slackdiff
    events: [post_store]
    token: SLACK_BOT_TOKEN
    channel: "#network-changes"
    proxy: http://myproxy:8080

Hook type: ciscosparkdiff

The ciscosparkdiff hook posts config diffs to a Cisco Spark space of your choice. It only triggers for post_store events.

You will need to manually install the cisco_spark gem on your system (see cisco_spark-ruby) and generate either a Bot or OAUTH access key, and retrieve the Spark Space ID

gem install cisco_spark

ciscosparkdiff hook configuration example

hooks:
  ciscospark:
    type: ciscosparkdiff
    events: [post_store]
    accesskey: SPARK_BOT_API_OR_OAUTH_KEY
    space: SPARK_SPACE_ID
    diff: true

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.

hooks:
  ciscospark:
    type: ciscosparkdiff
    events: [post_store]
    accesskey: SPARK_BOT_API_OR_OAUTH_KEY
    space: SPARK_SPACE_ID
    diff: false
    message: "%{node} %{group} %{model} updated https://git.intranet/network-changes/commit/%{commitref}"

Note the space and access tokens must be in quotes.

A proxy can optionally be specified if needed to reach the Spark API endpoint.

hooks:
  ciscospark:
    type: ciscosparkdiff
    events: [post_store]
    accesskey: SPARK_BOT_API_OR_OAUTH_KEY
    space: SPARK_SPACE_ID
    diff: true
    proxy: http://myproxy:8080

Hook type: xmppdiff

The xmppdiff hook posts config diffs to a XMPP chatroom of your choice. It only triggers for post_store events.

You will need to manually install the xmpp4r gem on your system:

gem install xmpp4r

xmppdiff hook configuration example

hooks:
  xmpp:
    type: xmppdiff
    events: [post_store]
    jid: "[email protected]/resource"
    password: "password"
    channel: "[email protected]"
    nick: "nickname"

Note the channel name must be in quotes.