Repository navigation
Server Configuration
Krampus is a simple Santa sync server, following Santa's sync protocol.
Krampus is written with modularity as a focus. Its main functionality can be found in krampus.py. This includes both the sync logic itself as well as all the required listeners for the sync, and krampusctl. However the database, authentication and event handling Krampus uses is all defined in different modules. So for instance, if Firestore is selected as Krampus' database, then the db_firestore.py module will be selected, imported and used by Krampus to store and retrieve Santa rules and hostconfigs. Which module is used is determined by which environment variables are present. For instance the Firestore database requires a GCP_PROJ_ID to setup, so this database type will be chosen if that environment variable is present. This page describes first which databases are currently supported by Krampus, and then all the environment variables Krampus requires, both for itself and for any specific chosen module.
Warning
If the rules and hostconfigs in the database do not have any targets they will never be sent to a machine. When using krampusctl to update the database, a default target of allis added to each rule and hostconfig if no target is given. If you populate the database without krampusctl this default target must be populated manually.
Krampus supports a handful of database backends, and you can also extend backend support with your own module. The databases supported by this repository are as follows:
| Name | Version (tested on) |
|---|---|
| Postgres | 18 |
| MySQL | 8.4 |
| Google Cloud Firestore | n/a |
This section details the environment variables that can be used to configure the Krampus server at runtime.
| Environment Variable | Default Value | Description |
|---|---|---|
MIN_CLEAN_SYNC_DAYS |
n/a | When choosing when a host will next perform a clean sync, Krampus pick randomly selects a number of days between the minimum value, and a maximum value. This environment variable sets the minimum value. |
MAX_CLEAN_SYNC_DAYS |
n/a | When choosing when a host will next perform a clean sync, Krampus pick randomly selects a number of days between the minimum value, and a maximum value. This environment variable sets the maximum value. |
BATCH_SIZE |
50 | Krampus sends rules to clients in batches, of BATCH_SIZE size at a time. If this environment variable is not set, Krampus will default to a batch size of 50 rules. |
Krampus requires a database to function, so all the environment variables for one of these databases must be present.
| Environment Variable | Default Value | Description |
|---|---|---|
POSTGRES_HOST |
n/a | FQDN/IP address of your Postgres instance. |
DB_NAME |
n/a | The name of your database within your Postgres instance. |
POSTGRES_PORT |
5432 |
The port number for your Postgres connection. |
POSTGRES_USER |
n/a | The Postgres username that Krampus should use. |
POSTGRES_PW |
n/a | The Postgres password that Krampus should use. |
| Environment Variable | Default Value | Description |
|---|---|---|
MYSQL_HOST |
n/a | FQDN/IP address of your MySQL instance. |
DB_NAME |
n/a | The name of your database within your MySQL instance. |
MYSQL_PORT |
3306 |
The port number for your MySQL connection. |
MYSQL_USER |
n/a | The MySQL username that Krampus should use. |
MYSQL_PW |
n/a | The MySQL password that Krampus should use. |
Important
The Firestore library handles authentication for Krampus. It assumes you are using Application Default Credentials.
| Environment Variable | Default Value | Description |
|---|---|---|
GCP_PROJ_ID |
n/a | The name of the Google Cloud project that your Firestore database is in. |
DB_NAME |
n/a | The name of the Firestore database you want to use with Krampus. |
Authentication for Krampus is optional. It is recommended that the Krampus is set up in an environment that already required authentication and a secure connection. Krampus' authentication functionality is considered additional protection and should not be the sole authentication method used.
| Environment Variable | Default Value | Description |
|---|---|---|
SYNC_SECRET |
n/a | A secret string that clients must provide as the value for the Krampus-Auth HTTP header. |
CTL_SECRET |
n/a | A secret string that krampusctl must provide as the value for the Krampus-Auth HTTP header. |
Warning
JWT is only implemented for the krampusctl api.
Important
Krampus uses HS256 as the algorithm to create the JWT. This is not configurable.
| Environment Variable | Default Value | Description |
|---|---|---|
JWT_USERNAME |
n/a | A username for registering with Krampus to create a JWT. |
JWT_PASSWORD |
n/a | A password for registering with Krampus to create a JWT. |
JWT_SECRET |
n/a | A secret string used by Krampus to generate the JWT. |
JWT_EXP_MIN |
5 | How many minutes a JWT token should be valid for. |
Event handling is optional, if no event handler is selected, events uploaded from the sync will simply be ignored.
Important
The Pub/Sub library handles authentication for Krampus. It assumes you are using Application Default Credentials.
| Environment Variable | Default Value | Description |
|---|---|---|
PUB_SUB_TOPIC_ID |
n/a | Google Cloud Pub/Sub topic name to forward client events to. Defaults to empty. |
PUB_SUB_PROJ_ID |
n/a | Name of the Google Cloud project that your Pub/Sub topic is in. |
| Environment Variable | Default Value | Description |
|---|---|---|
WEBHOOK_URL |
n/a | The url events should get sent to. |