Skip to content

# Nautobot ChatOps Installation Guide

This guide outlines the process of enabling Nautobot ChatOps, which includes:

- Nautobot ChatOps Installation Guide
- Prerequisites
  - Potential Apps Conflicts
- Chat Platforms Configuration
- Installation Guide
- Configuration Guide
- Granting Access to the Chat Platform
- Link Nautobot Account
- Test Your Chatbot
- Integrations Configuration

## Glossary

- Chat Platform: A communication service (e.g., Mattermost, Microsoft Teams, Slack, Cisco Webex).
- Command: A particular instruction sent by users via the Chat Platform, which is then processed by an Integration.
- Dispatcher: A class specific to the Chat Platform that processes incoming chat messages, executes commands, and sends results back to the Chat Platform.
- Integration: A component that defines commands, handles data retrieval, and manipulation for specific tools or services (e.g., IP Fabric, AWX / Ansible Tower, Palo Alto Panorama, Grafana, Cisco ACI, Cisco Meraki, Arista CloudVision).
- Platform View: A Django View designed to handle Chat Platform data.
- Sub-command: An instruction that is nested within a Command.
- Worker: A module within an Integration, designed to handle and process a Command, receiving data from Platform Views and returning results via a Dispatcher's generic API.

## Prerequisites

Ensure the following before beginning the installation:

- Nautobot 1.5.4 or higher is installed.
- Your chat platform can access Nautobot via an HTTPS URL.
  - Some chat platforms require SSL certificate verification to communicate with the Nautobot server.
  - For development, you may use HTTP.
- You have `sudo` access on the Nautobot server.
- You have administrative access within the Nautobot Web UI.

### Potential Apps Conflicts

Warning

If upgrading from `1.x` version to `2.x` version of `nautobot-chatops` App, note that it now incorporates features previously provided by individual apps.

Conflicting Apps list:

- `nautobot_plugin_chatops_aci`
- `nautobot_plugin_chatops_ansible`
- `nautobot_plugin_chatops_arista_cloudvision`
- `nautobot_plugin_chatops_ipfabric`
- `nautobot_plugin_chatops_grafana`
- `nautobot_plugin_chatops_meraki`
- `nautobot_plugin_chatops_panorama`

To prevent conflicts during `nautobot-chatops` upgrade:

- Remove conflicting applications from the `PLUGINS` section in your Nautobot configuration before enabling the latest `nautobot-chatops` version.
- Transfer the configuration for conflicting apps to the `PLUGIN_CONFIG["nautobot_chatops"]` section of your Nautobot configuration. See `development/nautobot_config.py` for an example. Each integration set up guide contains a chapter with upgrade instructions.
- Remove conflicting applications from your project's requirements.

These steps will help prevent issues during `nautobot-chatops` upgrades. Always back up your data and thoroughly test your configuration after these changes.

Warning

If conflicting Apps remain in `PLUGINS`, the `nautobot-chatops` App will raise an exception during startup to prevent potential conflicts.

## Chat Platforms Configuration

The `nautobot-chatops` package supports multiple chat platforms.

Set up your chosen chat platform:

- Mattermost
- Microsoft Teams
- Slack
- Cisco Webex

## Installation Guide

Note

Install the App manually or via Python's `pip`. For detailed information, visit the Nautobot documentation. The pip package for this App is `nautobot-chatops`.

Warning

Follow the Nautobot App Installation Instructions for complete and most recent guidelines.

The App is a Python package available on PyPI, installable with `pip`:

    pip install nautobot-chatops

To use specific integrations, add them as extra dependencies:

    pip install nautobot-chatops[ansible]

To auto-install Nautobot ChatOps during future upgrades, add `nautobot-chatops` to `local_requirements.txt` (create if not

present) in the Nautobot root directory, adjacent to `requirements.txt`:

    echo nautobot-chatops >> local_requirements.txt

After installation, enable the App in your Nautobot configuration by updating your `nautobot_config.py` file:

- Include `"nautobot_chatops"` in the `PLUGINS` list.
- Add the `"nautobot_chatops"` dictionary to `PLUGINS_CONFIG` and override defaults if necessary.

    # In your nautobot_config.py
    PLUGINS = ["nautobot_chatops"]

    PLUGINS_CONFIG = {
        "nautobot_chatops": {
            # ADD YOUR SETTINGS HERE
        }
    }

## Configuration Guide

Adjust the App's behavior with the following settings:

Configuration Setting | Description | Mandatory? | Default
--- | --- | --- | ---
`delete_input_on_submission` | Removes the input prompt from the chat history after user input | No | `False`
`restrict_help` | Shows Help prompt only to users based on their Access Grants | No | `False`
`send_all_messages_private` | Ensures only the person interacting with the bot sees the responses | No | `False`
`fallback_chatops_user` | Nautobot User for Chat Commands to use if the user has not linked their account | Yes | `chatbot`
`session_cache_timeout` | Controls session cache | No | `86400`

## Granting Access to the Chat Platform

Nautobot provides an HTTP endpoint(s) for each supported chat platform. Although these endpoints do implement authentication to prevent arbitrary HTTP requests from triggering bot actions, they can accept and act on any validly-formed request from the chat platform, which could originate from any organization, team, channel(room), or user who has access to the chat system.

For most realistic deployments, open and unrestricted access to the bot from any chat account is undesirable. Therefore, in this version, access to the chatbot defaults to "deny all" when initially installed, but varying scopes (per organization, per channel, per user) and degrees (all commands, all sub-commands of a single command, single sub-command of a single command) of access can be granted through Nautobot.

The access grants are maintained in Nautobot's database for persistence, and are change-logged like other Nautobot records.

Note that access grants are based on the chat platform's internal ID values for users, channels, and organizations; although you can and should attach a user-friendly name to each access grant for reference, it is the ID value that is actually enforced by Nautobot. On some platforms and for some access scopes, the Nautobot UI "Look up Value from Name" button can be used to auto-discover the ID value corresponding to a given name; if this fails, you can always attempt to send a request to Nautobot from the desired user/channel/organization and retrieve the ID value from the resulting error message to use to define a new access grant.

The specific access grants you will want to define will depend on your operational requirements, but some examples are provided below to help you get started.

### Example: Unrestricted Access Within a Single Organization

In the simplest realistic configuration example, access to all chatbot commands is granted for all users and all channels in a single organization scope.

Command | Sub-command | Grant type | Name | Value
--- | --- | --- | --- | ---
`*` | `*` | organization | my-org | `T202B88NN`
`*` | `*` | channel(room) | any | `*`
`*` | `*` | user | any | `*`

### Example: Split Command Access to Different Channels

In this example, Nautobot is providing two separate command groupings, each of which is intended for use by a different team within the organization. Each team has a dedicated channel on the chat platform, to which access is already controlled by other means, so we can allow all users within a given channel access.

Command | Sub-command | Grant type | Name | Value
--- | --- | --- | --- | ---
`*` | `*` | organization | my-org | `T202B88NN`
`support` | `*` | channel(room) | support | `C2020H455`
`devops` | `*` | channel(room) | devops | `C3030I566`
`*` | `*` | user | any | `*`

### Example: Restrict Specific Command and Sub-command to Specific Users in a Specific Channel

In this example, Nautobot has a potentially-destructive sub-command that should only be used by a handful of admin users. Other sub-commands under this sub-command can be used by anyone in the devops channel. Other commands are harmless fun and can be used by any user in the organization in any channel.

Command | Sub-command | Grant type | Name | Value
--- | --- | --- | --- | ---
`*` | `*` | organization | my-org | `T202B88NN`
`jokes` | `*` | channel(room) | any | `*`
`jokes` | `*` | user | any | `*`
`network` | `*` | channel(room) | devops | `C3030I566`
`network` | `history` | user | any | `*`
`network` | `redeploy` | user | admin1 | `U2049K991`
`network` | `redeploy` | user | admin2 | `U2039K725`
`network` | `redeploy` | user | admin3 | `U7924K784`
`network` | `status` | user | any | `*`
`weather` | `*` | channel(room) | any | `*`
`weather` | `*` | user | any | `*`

## Link Nautobot Account

+++3.0.0

Nautobot ChatOps now uses the built-in Nautobot permissions for Nautobot Objects (Devices, Locations, Racks, etc.). Each user will need to link their Nautobot Account with their Chat Platform User Account. Login to Nautobot then access the Link ChatOps Account within the Plugins menu. Here you can provide your email address and select the ChatOps Platform you are using, then click the Look up User ID from Email to get your Chat User ID.

A Nautobot user can have multiple Chat users connected, but the Chat User can only be linked to one Nautobot user. As an example my team is transitioning from Slack to Mattermost. My Slack User ID and my Mattermost User ID can both be connected to the same Nautobot User.

### Configuring Account Link for many users

Admins have the ability to access the Nautobot Admin page and can use `ChatOps Account Links` page to link multiple accounts, but you will need to know the Chat Platforms user IDs for each user you are linking.

## Test Your Chatbot

Finally, test your chatbot's functionality within your chosen chat application, using a command like `/nautobot get-devices`.

## Integrations Configuration

The `nautobot-chatops` package includes multiple integrations. Each requires extra dependencies defined in `pyproject.toml`. See the installation guide for instructions on installing these dependencies.

Set up integrations using the specific guides:

- Cisco ACI
- AWX / Ansible Tower
- Arista CloudVision
- Grafana
- IPFabric
- Cisco Meraki
- Palo Alto Panorama