This functionality was introduced with Squirro 3.3.3.

Table of Contents

Overview

With Squirro 3.3.1, the updated configuration service was introduced and has been promoted to the central place for all Squirro configuration. Before that, the service had been present but was only used for a selected few keys.

Over time the configuration service will replace the individual Configuration Files. The only aspect currently excluded from this strategy are any security-relevant configuration (see Securing your Configuration Files) and settings that are required for Squirro’s services to boot up.

The configuration service can be used for user-defined settings. Note however, that the maximum size of a value is around 4kb. As a result, the configuration service is not meant as a generic data storage layer.

Setting and Accessing Values

User Interface

The server-level settings are accessible through the Configuration screen in the Server space.

Any exposed value can be edited through the user interface. A built-in value that has been modified can be reset to its default value.

Additionally custom settings can be added. When doing so, the data type can be selected, with the configuration service providing values of type string, number, boolean or dictionary (a rich JSON data structure).

Changes are not applied instantaneously, the Caching settings will affect how long it takes for services to see updates.

Automated Setting

When provisioning a Squirro server automatically, for example with Ansible, you may want to seed some configuration settings.

This can be done by adding JSON files into the folder /etc/squirro/configuration.d. Only files with the .json extension are considered. The folder and its files need to be readable by the configuration service user (sqconfig). Files that are invalid or unreadable will prevent the configuration service from starting. Consult the log file /var/log/squirro/configuration/configuration.log to see details if that happens.

When adding or changing values in this folder, the sqconfigurationd service needs to be restarted (see Services). On top of that, the Caching settings will affect how long it takes for services to see updates.

Overwriting built-in settings

To overwrite settings that Squirro provides out of the box, use a file with the following content:

{
    "key": "user.create",
    "default_value": false
}

This will change the key user.create to be disabled. This however merely changes the configuration service’s default value for the key. Server administrators can then change the key in the frontend.

If the same key is referenced in multiple files, the last one will win.

Add custom settings

Additional settings can be added and will be exposed the exact same way as any built-in setting. The snippet for overwriting built-in settings will work for these too, but a few more keys are recommended:

{
    "key": "app.disabling-test",
    "namespace": "server",
    "help": "This help text is exposed to users when editing the key in the user interface.",
    "type": "boolean",
    "default_value": true
}

Handle project settings

Project-specific settings are recorded in the project namespace. They can be defined either for all projects or for a specific one like this:

{
    "key": "app.project-test"
    "namespace": "project",
    "help": "A test for project setting. Value can be changed per project.",
    "type": "number",
    "default_value": 42
}

This declares a new configuration key app.project-test which can then be accessed through the API.

It is also possible to define a value for a specific project by providing the scope property:

{
    "key": "app.project-test"
    "namespace": "project",
    "scope": "XW1vSnxiRp-O4XCvJrA5Jg",
    "help": "A test for project setting. Value can be changed per project.",
    "type": "number",
    "default_value": 42
}

Full Reference

All the properties that can be set and their possible values.

...

Property

...

Description

...

key

...

The key with which the setting is exposed. The keys need to follow specific naming conventions, see the section Naming Keys.

Keys are globally unique, independent of their namespace. So if you declare a app.my-setting key in the user namespace, a different setting of the same name can not exist in the project namespace.

...

namespace

...

The namespace under which to expose the key. The key needs to be globally unique, so a server-level setting can not have the same key as a user-level setting for example.

Possible namespaces are:

• server

• project

• user

...

scope

...

The namespace-specific scope in which a key is available.

Not used for server namespace.

For project and user namespaces this points to the project ID or user ID respectively. But in both cases it can be left out or set to null to define the global default value.

...

help

...

A description of the key’s purpose, presented to the administrator when editing the key in the user interface.

...

type

...

The value type. Possible types are:

• string

• number

• boolean

• dictionary (stored and represented as a JSON dictionary)

...

default_value

...

The default value for this setting. Manually defined settings, such as through the user interface or the API, will always take precedence over this.

Squirro Client

The configuration service can be accessed through the Python client. See the ConfigurationMixin documentation for the available methods.

Implementation Details

Caching

All configuration service lookups are cached, and there is no support for flushing the cached values (short of restarting all services). The config.cache-ttl setting determines how long the settings are cached.

That setting itself is cached as well, so changing it will also take some time to have an effect.

Naming Keys

The configuration keys are validated to the following rules:

...

Include one or more sections separated by periods. To avoid naming clashes, we recommend you use the reserved app section.

...

Sections are lowercase and can not include any numbers or other characters.

...

This page can now be found at Configuration Service on the Squirro Docs site.