Operations Overview

Starting quokka

The quokka server, which provides most of the quokka functionality, runs as a flask application, and is built following the tutorial examples that exist in the flask documentation. As such, quokka starts when flask is run in the quokka directory with the flask run command.

You can see this in the run-all.sh and run-quokka.sh scripts.

Quokka entry point

When flask is run as above, it will look at the file init.py - this is a flask-specific thing. But that means, if you want to look at how quokka works, the place to look is at the main init.py file.

Note that Python makes liberal use of "init", so there will be other files by this name. We are talking about the main init.py file, which is located at quokka/quokka/__init__.py

Quokka startup steps

Looking at this init.py file, you will notice that the startup steps include the following:

• Initiation of main Flask object app = Flask(__name__)
• Gathering values of environment variables for monitoring intervals for devices, hosts, services, configurations, discover, etc.
• Declaration of database, and all the 'models' (these are the DB tables representing devices, hosts, services, etc.)
• Declaration of the 'views' (these are the REST APIs that exists, by which the 'outside world' communicates with quokka
• Importing of devices, services, workers, etc., from YAML configuration files
• Starting of threads for performing ongoing monitoring tasks for devices, hosts, services, getting configs, performing hourly summaries, etc.
• Initialization of 'remote worker' managers for packet capture, port scan, and traceroute

Once these startup functions complete, quokka is done initializing, and is running inside the Flask application, waiting for things to happen.

Quokka ongoing operation

At this point, Quokka has been initialized: the database is started and ready to use, the REST API is started and ready to be called, and the threads have been started and will proceed at their own pace.

So, as alluded to in the sentence above, the following actions will cause quokka to 'wake up' and perform work:

• REST APIs: Quokka has multiple types of REST APIs:

  • UI: Quokka has a full set of REST APIs for allowing the UI to get information about devices, hosts, services, status, summaries, etc.
  • Worker: Quokka workers send heartbeat messages to Quokka, letting quokka know it is alive, and in some cases, retrieving commands to execute
  • Capture/Portscan/Traceroute: Quokka receive results of packet captures, port scans, and traceroutes, via this REST API
  • Device: Certain device types, e.g. my simulated SDWAN devices, can communicate only using the REST API, sending heartbeats, receiving commands, etc.

• Monitoring: Quokka spawns a number of monitoring threads when it starts, and these run all the time, as long as the quokka server is up. These threads run at specific "intervals" which are configurable, e.g. every 5 minutes, every hour, etc. These monitoring threads include:

  • Device Monitoring: This includes two different threads, on for monitoring device status (availability, response time, CPU and memory utilization), as well another thread for monitoring compliance (software version and configuration).
  • Host Monitoring: The host monitoring thread attempts to ping the hosts, and records their availability and response time.
  • Service Monitoring: The service monitoring thread attempts to access the defined services, using mechanisms appropriate for the service (e.g. for HTTP, making an HTTP request; for NTP, making an NTP request, for DNS, making a DNS request). Currently only these services are implemented, but more could be added.
  • Summaries: Every hour, at the top of the hour, the summaries thread will gather response time and availability information, average them for the hour, and save those summaries in the DB.