diff --git a/docs/docs/adding-devices.mdx b/docs/docs/adding-devices.mdx index 126d8a1..81dfaae 100644 --- a/docs/docs/adding-devices.mdx +++ b/docs/docs/adding-devices.mdx @@ -14,6 +14,30 @@ import Code from "../src/components/JSXCode";
+## Adding Devices + +To add, as an example, a Cisco router, add the following to your `devices.yaml`, with the relevant details changed for your device: + +```yaml title="devices.yaml" +routers: + - name: router01.pop01 + address: 10.0.0.1 + network: AS65000 + credential: + username: username + password: password + location: pop01 + display_name: Phoenix, AZ + port: 22 + nos: cisco_ios + vrfs: + - name: default + ipv4: + source_address: 192.0.2.1 + ipv6: + source_address: 2001:db8::1 +``` + ## All Device Parameters | Parameter | Type | Description | @@ -103,7 +127,7 @@ May be set to `null` to disable IPv6 for this VRF, on the parent device. :::note The `force_cidr` option will ensure that a **BGP Route** query for an IP host (/32 IPv4, /128 IPv6) is converted to its containing prefix. For example, a query for `1.1.1.1` would be converted to a query for `1.1.1.0/24`. This is because not all platforms support a BGP lookup for a host (this is primary a problem with IPv6, but the option applies to both address families). -When `force_cidr`is set to `true`, hyperglass will perform a lookup via the [RIPEStat](https://stat.ripe.net/docs/data_api#network-info) Data API to get the advertised prefix for an IP host. +When `force_cidr`is set to `true`, hyperglass will perform a lookup via the [bgp.tools](https://bgp.tools) whois API to get the advertised prefix for an IP host. ::: #### `access_list` @@ -130,20 +154,24 @@ Each VRF may enable, disable, or customize the contextual help menu for each ena For example: ```yaml title="devices.yaml" -info: - bgp_route: - enable: true - file: /etc/hyperglass/customer_bgp_route.md - params: - vrf_name: Customer A - ping: - enable: false - bgp_community: - enable: true - file: /etc/hyperglass/customer_bgp_community.md - params: - vrf_name: Customer A - community: "65000" +routers: + - name: router01 + vrfs: + - name: demo_vrf + info: + bgp_route: + enable: true + file: /etc/hyperglass/customer_bgp_route.md + params: + vrf_name: Customer A + ping: + enable: false + bgp_community: + enable: true + file: /etc/hyperglass/customer_bgp_community.md + params: + vrf_name: Customer A + community: "65000" ``` ## Telnet @@ -251,3 +279,99 @@ routers: password: pass nos: linux_ssh ``` + +## YAML Anchors & Aliases + +If you have a lot of devices with shared configuration parameters, you may want to look into **YAML Anchors and Aliases**. If you've never used them before, they can be pretty weird looking at first read. Atlassian [has a pretty decent guide](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html). + +Here's an example of using this to share two sets of credentials among multiple devices: + +```yaml title="devices.yaml" +my_credentials: + - credential: &credential1 + username: madeup1 + password: gY018mR4gx4sVqc0 + - credential: &credential2 + username: madeup2 + password: 0eMEJ4ZpB6ofkiIF + +routers: + - name: router01 + credential: *credential1 + - name: router02 + credential: *credential2 + - name: router03 + credential: *credential1 + - name: router04 + credential: *credential2 +``` + +:::important +Nothing other than the `routers` key is read by hyperglass. In the above example, `my_credentials` is just an arbitrary list of mappings, is completely optional, and can be named whatever you want. +::: + +For a more complex example, here's an example of how to use YAML aliases & anchors to share a common VRF configuration among multiple devices, while overriding key variables such as the `source_address` key: + +```yaml title="devices.yaml" +my_vrfs: + - &default + name: default + display_name: Global + ipv4: + access_list: &default_ipv4_acl + - network: 10.0.0.0/8 + action: deny + - network: 192.168.0.0/16 + action: deny + - network: 172.16.0.0/12 + action: deny + - network: 0.0.0.0/0 + action: permit + ge: 8 + le: 24 + ipv6: + access_list: &default_ipv6_acl + - network: ::/0 + action: permit + ge: 32 + le: 64 + - &customer_a + name: customer_a + display_name: Customer A + ipv4: + access_list: &customer_a_ipv4_acl + - network: 10.0.0.0/8 + action: permit + - network: 0.0.0.0/0 + action: deny + ipv6: null + +routers: + - name: router01 + vrfs: + - <<: *default + ipv4: + source_address: 192.0.2.1 + access_list: *default_ipv4_acl + ipv6: + source_address: 2001:db8::1 + access_list: *default_ipv6_acl + - <<: *customer_a + ipv4: + source_address: 10.0.0.1 + access_list: *customer_a_ipv4_acl + + - name: router02 + vrfs: + - <<: *default + ipv4: + source_address: 192.0.2.2 + access_list: *default_ipv4_acl + ipv6: + source_address: 2001:db8::2 + access_list: *default_ipv6_acl + - <<: *customer_a + ipv4: + source_address: 10.0.0.2 + access_list: *customer_a_ipv4_acl +``` diff --git a/docs/docs/parameters.mdx b/docs/docs/parameters.mdx index 655d0c4..172949e 100644 --- a/docs/docs/parameters.mdx +++ b/docs/docs/parameters.mdx @@ -59,22 +59,6 @@ The following global settings can be set in `hyperglass.yaml`: The `netmiko_delay_factor` parameter should only be used if you're experiencing strange SSH connection issues. By default, Netmiko uses a `global_delay_factor` of `1`, which tends to be a bit slow for running a simple show command. hyperglass overrides this to `0.1` by default, but you can override this to whatever value suits your environment if needed. ::: -#### Example - -```yaml title="hyperglass.yaml" -debug: false -developer_mode: false -org_name: Beloved Hyperglass User -site_title: hyperglass -site_description: "{org_name} Network Looking Glass" -site_keywords: [hyperglass, looking glass, routing, bgp] -request_timeout: 30 -listen_address: "127.0.0.1" -listen_port: 8001 -log_file: /tmp/hyperglass.log -cors_origins: [localhost:3000, 192.0.2.1] -``` - ### Subsections From the top level, the following subsections may be defined and configured: @@ -89,32 +73,18 @@ From the top level, the following subsections may be defined and configured: | `structured` | Configure structured data features. | ➡️ | | `web` | Web UI & branding settings. | ➡️ | -## Adding Devices +### Example -To add, as an example, a Cisco router, add the following to your `devices.yaml`, with the relevant details changed for your device: - -```yaml title="devices.yaml" -routers: - - name: router01.pop01 - address: 10.0.0.1 - network: AS65000 - credential: - username: username - password: password - location: pop01 - display_name: Phoenix, AZ - port: 22 - nos: cisco_ios - vrfs: - - name: default - ipv4: - source_address: 192.0.2.1 - ipv6: - source_address: 2001:db8::1 +```yaml title="hyperglass.yaml" +debug: false +developer_mode: false +org_name: Beloved Hyperglass User +site_title: hyperglass +site_description: "{org_name} Network Looking Glass" +site_keywords: [hyperglass, looking glass, routing, bgp] +request_timeout: 30 +listen_address: "127.0.0.1" +listen_port: 8001 +log_file: /tmp/hyperglass.log +cors_origins: [localhost:3000, 192.0.2.1] ``` - -There are a lot more options, but this is enough to get started. For all device configuration options, [see here](adding-devices). - -:::tip YAML -If you have a lot of devices with shared configuration parameters, you may want to look into **YAML Anchors and Aliases**. If you've never used them before, they can be pretty weird looking at first read. Atlassian [has a pretty decent guide](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html). -::: diff --git a/docs/static/sitemap.xml b/docs/static/sitemap.xml deleted file mode 100644 index d3f12db..0000000 --- a/docs/static/sitemap.xml +++ /dev/null @@ -1,94 +0,0 @@ - - - - https://hyperglass.io/docs/adding-devices - - - - https://hyperglass.io/docs/commands - - - - https://hyperglass.io/docs/getting-started - - - - https://hyperglass.io/docs/introduction - - - - https://hyperglass.io/docs/license - - - - https://hyperglass.io/docs/logging - - - - https://hyperglass.io/docs/messages - - - - https://hyperglass.io/docs/parameters - - - - https://hyperglass.io/docs/platforms - - - - https://hyperglass.io/docs/production - - - - https://hyperglass.io/docs/query-settings - - - - https://hyperglass.io/docs/response-caching - - - - https://hyperglass.io/docs/rest-api - - - - https://hyperglass.io/docs/setup - - - - https://hyperglass.io/docs/table-output - - - - https://hyperglass.io/docs/upgrading - - - - https://hyperglass.io/docs/agent/installation - - - - https://hyperglass.io/docs/agent/setup - - - - https://hyperglass.io/docs/ui/configuration - - - - https://hyperglass.io/docs/ui/example - - - - https://hyperglass.io/docs/ui/logo - - - - https://hyperglass.io/docs/ui/text - - - - https://hyperglass.io/docs/ui/theme - -