Usage - chuckablack/quokka GitHub Wiki

This section describes what quokka does, and how to use it.

Note: if you are using the quokka OVA and want information about how to use it, go here: quokka ova

Overview of Features

Quokka does a number of things, primarily with the following entities:

  • Devices: networking devices such as switches, routers, wireless devices, WAN devices, etc.
  • Hosts: anything on the network with an IP address, such as laptops, desktops, phones, tablets, even WiFi doorbells, outlets, TVs, etc.
  • Services: services such as HTTP, DNS, NTP, etc.

Auto-discovery and configuration

  • Devices are configured by the user, and are monitored currently either through NAPALM or via NETCONF, using the ncclient library.
  • Hosts are automatically discovered, using a simple ping-sweep, currently only for the local subnet (but configuration of subnets to be discovered will probably be added soon), and are monitored using ping.
  • Services are configured by the user, and are monitored according to the service (e.g. HTTP is monitored by making an HTTP request, DNS via making a DNS request, etc.)

Continuous monitoring

  • Devices are continually monitored, currently on 5 minute intervals, for availability and response time. In addition, quokka examines compliance for the software version of the OS, and compliance for the standard configuration. (note that due to some issues with NAPALM, the configuration compliance is questionable, and requires some work).
  • Hosts are continually monitored, currently on 5 minute intervals, for availability and response time. In addition to this, quokka summarizes these values hourly, and records the hourly average response time and availability. Quokka currently has arbitrary SLA values set, which are displayed, and events generated, for whether the SLA is being met or not.
  • Servcies are continually monitored, currently on 5 minute intervals, for availability and response time. In addition to this, quokka summarizes these values hourly, and records the hourly average response time and availability. Quokka currently has arbitrary SLA values set, which are displayed, and events generated, for whether the SLA is being met or not.

On-demand diagnostics

  • Packet capture: For devices, hosts, and services, it is possible to initiate packet capture, to see what is going on on the network. Be aware that the packet capture only sees what your quokka server can see (e.g. promiscuous mode helps). You can have remote workers perform this function (see below).
  • Port scan: For hosts, it is possible to do a port scan, which shows open ports, and attempts to discern useful information about the host it is scanning.
  • Traceroute: For devices, hosts, and services, it is possible to run a traceroute, which will present a picture of the route between the quokka server and whatever the destination is (device, host, service).

Checking device configuration and software version

  • Config diff: For devices, it is possible to perform a config diff. This process reads the configuration regularly from devices, storing it, and doing a diff just compares the current config, with previous configs, showing the first config with a difference.

Events

Quokka has an event log and display, which shows events that have occurred, including things such as unavailability of devices, hosts, and services, and also SLA violations for services.

Configuration

There are a number of configuration files that provide information to quokka which allows it to run and monitor the items of interest to the user. These configuration files are in YAML format They include:

  • Configuration of devices and services. Note that if you just want to check out quokka, then no configuration of these files is required, as the devices will be Cisco's sandbox always-available devices, and the DNS, HTTP, and NTP services should be accessible from anywhere.
  • Details for diagnostic functions which can be run 'remotely', such as the monitors for doing packet capture, port scanning, and traceroute. However, if you are running these locally (as you will be at first), then no configuration of these files is required.
  • Configuration of remote workers, although if these are running locally (as initially), then no configuration of workers is required.

Remote workers

For certain features, it may be desirable to have the functionality run on a system other than the quokka server. For these cases, quokka supports what it calls "remote workers". These are small programs that listen for commands from the quokka to perform certain functions, and to return the results. The following functions have remote worker capability:

  • Packet capture
  • Port scan
  • Traceroute

Running quokka

When quokka is running, there are two main applications at work:

  • Quokka server: The quokka server is the "main" quokka application. is written in Python.
  • Quokka UI: The quokka UI is the functionality that makes the nifty user interface work. It is written in Javascript.

All quokka components can be run independently, but there are scripts to run subsets of the functionality. The simplest one is called 'run-all.sh', and running this will do the following:

  • Start the quokka server
  • Start the quokka UI
  • Start the 'remote workers' (which by default are running locally)

There is also a script called 'stop-all.sh', which will stop all quokka components.

In greater detail: