Managing the stack

This stage will let you configure your running stack, adding/removing PMUs, configuring accounts etc.

Preconditions

This assumes you have the full stack up and running.

Accessing the Workbench

Make sure your cluster information is sourced, and open the workbench with:

bin/qs-wb.sh

This command will drop you into the workbench environment inside the cluster.

In the workbench, you will find the following scripts:

1. accounts - Allows you to manage user accounts for Mr. Plotter, and their respective permissions
2. upmu-adm - Allows you to manage data from uPMUs and create configuration files for interacting with uPMUs
3. manager - Allows you to interact with uPMUs using the configuration files created by upmu-adm
4. mongo.sh - Allows you to interact directly with the Mongo database and manipulate the stream metadata in a raw format
5. set-selfsigned-certs.sh - If you did not use GEN_SSL when setting things up (for example, if you do not have a global IP Address), then you can generate a self-signed certificate to use with Mr. Plotter using this script. Run this script, and then restart Mr. Plotter.
6. remove - Allows you to remove streams from the plotter (such as distillates).

Interacting with uPMUs

upmu-adm can be used to generate and a configuration file (upmuconfig.ini), which describes a desired configuration (i.e., state) of all uPMUs known to the system. Creating this configuration file does not actually interact with the uPMUs; it simply produces a description of the desired state.

The manager2lite.py script, when run, reads the configuration file (upmuconfig.ini), and interacts with the metadata database in Mongo to update the desired state. This may involve adding uPMUs to the system, removing uPMUs from the system, and modifying the metadata of existing uPMUs.

We now explain how to use upmu-adm to read and modify the configuration file. You must run ./manager2lite.py in order to actually change the state of the system.

Using upmu-adm

These are the important commands:

1. add - A command such as "add 192.168.1.24 P3112233 alameda_server" adds to the configuration file a new uPMU with the IP address 192.168.1.24, with the serial number P3112233, and with the human-readable alias "alameda_server"
2. rem - Removes a uPMU from the configuration file. A uPMU can be specified by its IP Address, serial number, or alias
3. list - Lists the uPMUs in the configuration file, along with the IP addresses and aliases
4. save - Writes the changes in the current session to upmuconfig.ini. If you don't execute this command, the configuration file won't actually be modified.
5. importdat - Performs batch import of data from .dat files in the specified directory.

Using manager2lite.ipy

After modifying the configuration file using upmu-adm, execute ./manager2lite.ipy to effect the changes.

Each it is run, manager2lite.ipy makes a copy of the configuration file and stores it in /etc/sync/backupconfig.ini. When it is run, it looks at the diff between upmuconfig.ini and /etc/sync/backupconfig.ini, and operates based on that. If passed the --update-all command line flag, it performs a hard update based on upmuconfig.ini, which is useful if the Mongo state was changed by something other than manager2lite.ipy, causing /etc/sync/backupconfig.ini to fall out of date.

If you added or removed uPMUs from the system, it is recommended to also restart the "receiver" service for improved log output, although this is not necessary.

User Accounts for Mr. Plotter

Mr. Plotter supports permission-based access to data.

The system used to grant access is as follows: Users are granted access to a set of tags. Each tag represents a set of streams. The reason we use tags, as opposed to assigning users access directly to streams, is that tags allow groups of streams to be treated as a single unit when managing permissions. This is usually more convenient than assigning permissions to streams directly.

Defining Tags

The set of streams represented by each tag is in /etc/mrplotter/tagconfig.json within the workbench (which maps to /srv/mrplotter on the physical server).

/etc/mrplotter/tagconfig.json is a JSON document that represents the set of streams that each tag represents. Each key of the JSON file is a tag. The value corresponding to a tag is a list containing prefixes for the paths of streams represented by that tag. For example, consider the mapping:

{
    "public": ["/upmu/soda_a/", "/upmu/soda_b", "/upmu/culler", "/upmu/psl_alameda"],
    "all": ["/"]
}

All users who have access to the "public" tag can view data for streams whose paths begin with "/upmu/soda_a/", "/upmu/soda_b", "/upmu/culler", and "/upmu/psl_alameda". Users who have access to the "all" tag can view data for streams whose paths begin "/". All streams have paths beginning with "/", so any users who have permissions for the "all" tag can see data for all streams.

Note: The tag named "public" is special. If a visitor to the plotter is not logged in, they will be able to see streams corresponding to the tag "public". Likewise, "public" streams are automatically accessible to all users, even if they have not explicitly been granted access to the "public" tag.

Manging Users and Granting Permissions

The script "accounts" in the directory /wb is a tool for managing accounts for Mr. Plotter. Here are the commands:

1. adduser - Creates a new user for the plotter. You must specify the username and initial password, and you can optionally specify the tags that the user has access to.
2. addtags - Allows you to grant a user access to additional tags.
3. rmtags - Allows you to revoke access to tags from a use.
4. lstags - Lists the tags to which a specified user has access.
5. lsusers - Lists the users for the plotter.
6. ls - Lists the users and the tags to which they have access.
7. rmuser - Removes a user for the plotter.
8. setpassword - Changes a user's password.
9. exit - Cleanly exits the interpreter.
10. close - Cleanly exits the interpreter.
11. help - Prints the list of available commands.