Open Quarter Master Station Captain Guide

More information available on GitHub

1. Introduction

This document is a guide to using the oqm-captain utility. This script exists to manage your instance of Open QuarterMaster.

Due to the administrative tasks this script performs, it must be run as root, or with sudo.

2. Modes

This script supports several methods (modes) of interaction.

2.1. Interactive

This is the default mode, run when no arguments are passed. This provides a simple, console-based interface. When running from the system app icon, this is the mode that is run.

To navigate, use arrow keys.

To confirm an action, hit enter.

To select/deselect an option, press space.

You can also navigate by clicking on the menu items you want to select.

2.1.1. Flow

When starting up, the script performs a quick check to ensure the core system is installed. If the core components are not installed, it will prompt you to install them.

TODO more to say here? Update at least?

2.1.2. Menu System

This is a quick explanation of the menus in interactive mode, and what the tool allows you to do.

(main menu)

Info / Status
1. Installation Status
  - Shows how the installed services are running
  - Shows what versions of the software are running (TODO)
2. Host Information
  - Shows information about the host, including:
    
    IP addresses
    
    Hardware information
    
    Storage usage
    
    RAM usage
Manage Installation
1. Select OQM major version TODO, later
2. SSL/HTTPS Certs TODO
  1. Cert info TODO
    
    Shows the info about the certs that are currently setup for use
  2. Verify certificates
    
    Verifies that the certs setup are verifyable and valid for use
  3. Cert mode (self, Let’s Encrypt, provided)
  4. Private Key Location
  5. Public Cert/Key Location
  6. Cert mode specific Options
    
    Self signed Options
    
    CA Private Key Location
    
    Country Name
    
    Country Name
    
    State or Province Name
    
    Locality Name
    
    Organization Name
    
    Organizational Unit Name
    
    Let’s Encrypt Options
    
    Provided Options
    
    CA Provided
3. Core? TODO
  1. Ensure installed? (TODO)
  2. Common config options (TODO)
4. Set Email Settings
  TODO- document better
  - This menu sets email settings used to send emails from the system
  - These settings are used by various services as well as the system itself
  - Also supports testing these settings
5. User Administration
  Utilities to manage users in the system, and high level setup of how users are treated in the system.
  TODO- explain Keycloak and how it works. Links to additional resources.
  1. Goto keycloak admin console
    Shows the link to the admin console, and the credentials to login as the admin.
  2. Toggle self-register (TODO)
6. Plugins TODO
7. Uninstall All TODO
Snapshots
Snapshots allow you to take a current state of you system, and save it or back it up for later.
1. Restore from Snapshot
  Restores your system to the state from a given snapshot. Will bring down services momentarily while the restore occurs.
2. Perform snapshot now Performs a snapshot. Will bring down services momentarily while the snapshot occurs.
3. Enable/disable automatic snapshots Enables or disables snapshots from automatically taking place.
4. Set Snapshot location Sets the location the resulting snapshots are placed.
5. Set number of snapshots to keep Sets the number of snapshots to keep around. This is meant to preserve disk space.
6. Set automatic snapshot frequency Sets how often the automatic snapshots will occur.
Cleanup, Maintenance, and Updates
1. Updates
  This lets you update your system and change your automatic update settings
  1. Perform Updates (OS and OQM)
    This will update your system.
    Currently supports both apt and yum based systems; Debian/Ubuntu, Fedora/RHEL
  2. Enable/disable automatic updates
    This will prompt you on your os-specific menu to set automatic updates as enabled or not.
    Currently only supports Ubuntu, probably also Debian systems.
2. Containers
  1. Prune unused container resources
  2. Enable/disable automatic prune
  3. Set prune frequency
3. Data Management
  1. Clear ALL Data
  2. Clear OQM Data TODO
  3. Clear User Data TODO
  4. Clear Plugin Data TODO
4. Dump Logs
  Dumps logs to an archive, intent to be able to send that file for debugging. Puts them in a subdirectory under where snapshots are placed.
5. Restart all services
  - Restarts all services related to OQM
  - Recommended do after config changes and during low usage times.
6. Restart Device
  - Does as advertises. Restarts the system that this all runs on.
  - Recommended when weirder issues occur, and after updates.
Captain Settings TODO

2.2. Python UI (Planned/TODO)

A more user-friendly interface than the standard menu system. Follows the same menu system and layout.

This is a planned feature, so stay tuned.

2.3. Command

A command line interface is available for performing operations with a single action.

Use oqm-captain -h for information in the available options.

3. OQM Config

OQM Config is a secondary utility that sits alongside oqm-captain, and helps facilitate a smooth operation. Specifically, like it’s name implies, it handles the configuration for the system.

More guide to come in the future.