some file

Management SQLite store

SQLite is the default storage engine for NetBird Management. It requires no external dependencies and works out of the box for new installations.

If you need concurrent access or high availability with multiple management instances, consider using PostgreSQL instead.

SQLite entity relationship diagram

For a high-level overview of the SQLite schema, refer to the Entity Relationship Diagram (ERD) below:

high-level-dia

Configuration

Combined setup (config.yaml)

SQLite is the default engine. If you need to explicitly set it in your config.yaml:

server:
  store:
    engine: "sqlite"

Confirm SQLite is active by checking the server logs on startup:

docker compose logs netbird-server

You should see:

INFO management/server/store.go:77: using SQLite store engine

For a full list of available configuration options, see the config.yaml.example reference file.

Older multi-container setup (management.json)

This section applies to deployments using the older multi-container architecture with separate management, signal, relay, and coturn containers. If you deployed using the getting-started.sh script, you are on the combined setup and should use the config.yaml instructions above. See the migration guide to upgrade.

To enable SQLite, add to your setup.env:

NETBIRD_STORE_CONFIG_ENGINE=sqlite

This sets the following in your management.json:

    "StoreConfig": {
        "Engine": "sqlite"
    }

Migrating from JSON store to SQLite store

This migration only applies to the older multi-container setup. The combined setup has always used SQLite by default and does not support JSON file storage.

Since version 0.28.0, support for JSON file storage has been removed. All installations should be on SQLite or PostgreSQL.

This migration process allows users to seamlessly transition from JSON file storage to SQLite while maintaining data integrity. Ensure that you are running the commands described below after upgrading to version 0.24.0 or later.

Migration commands

Starting from version 0.24.0, NetBird Management provides a subcommand to facilitate migration to SQLite. This command is part of the binary shipped within the official docker image.

The following commands assume you use the latest docker version with the compose plugin. If you have docker-compose installed as a standalone, please use docker-compose as a command.

$ docker exec -it netbird-management /go/bin/netbird-mgmt sqlite-migration

This will produce an output similar to:

Contains sub-commands to perform JSON file store to SQLite store migration and rollback

Usage:
  netbird-mgmt sqlite-migration [command]

Available Commands:
  downgrade   Rollback SQLite store to JSON file store. Please make a backup of the SQLite file before running this command.
  upgrade     Migrate JSON file store to SQLite store. Please make a backup of the JSON file before running this command.

Flags:
      --datadir string   server data directory location (default "/var/lib/netbird/")
  -h, --help             help for sqlite-migration

Global Flags:
      --log-file string    sets Netbird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/management.log")
      --log-level string   (default "info")

Use "netbird-mgmt sqlite-migration [command] --help" for more information about a command.

Follow these steps for migration:

To migrate from JSON file store to SQLite, follow these steps:

The following commands assume you use the latest docker version with the compose plugin. If you have docker-compose installed as a standalone, please use docker-compose as a command.

  1. After accessing the path that contains your docker-compose.yml and management.json files, stop the NetBird Management service.
  docker compose stop management
  1. Backup your data store (store.json in datadir - default "/var/lib/netbird/").
  mkdir backup
  docker compose cp -a management:/var/lib/netbird/ backup/
  1. Start NetBird Management service:
  docker compose start management
  1. Run the migration to SQLite subcommand:
  docker exec -it netbird-management /go/bin/netbird-mgmt sqlite-migration upgrade --log-file console
  1. Enable SQLite by updating the management.json file and setting the Engine field to sqlite:
    "StoreConfig": {
        "Engine": "sqlite"
    }
  1. Restart the Management service.
  docker compose restart management
  1. Check logs to confirm the store switch:
  docker compose logs management

You should see an entry similar to:

2023-10-19T18:55:29Z INFO management/server/store.go:75: using SQLite store engine