# Configuration Service Squirro’s configuration service is the centralized repository for server, project, and user configuration. ## Overview The configuration service is the central place for all Squirro configuration. 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 of the Squirro UI. 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](../operations/services.md#admin-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: ```python { "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 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: ```python { "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: ```python { "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: ```python { "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 } ``` As of version 3.4.4 the project settings are also exposed outside of the API. See [Project Configuration](../../templates/project-configuration.md#project-templates-configuration) for more details. ## 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`](../../../api/squirro_client.topic.ConfigurationMixin.md#squirro_client.topic.ConfigurationMixin) documentation for the available methods. ## 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. - The ultimate key (the part after the last period) can consist of lowercase letters, numbers, and dashes.