Multi Account

Multi Account BindPlane is an Enterprise feature that allows users to create multiple tenants (accounts). Each account can have its own users, configurations, and managed agents. Multi Account support user invitation in order to support collaboration between multiple users.

Objective

After upgrading from BindPlane OP Open Source to BindPlane OP Enterprise, you want to convert the single account Bolt Store configuration into a multi account configuration using Bolt Store or PostgreSQL.

Prerequisites

The following requirements must be met:

You are running BindPlane OP Enterprise. See Upgrade to BindPlane OP Enterprise.
You must have SSH access to the BindPlane server(s).
You must have BindPlane cli access to the BindPlane server(s).
BindPlane OP v1.25.0 or newer. If on an older version, upgrade before attempting a migration.
Optional: You have a PostgreSQL server and database configured for BindPlane to use.
- Not required if using the default bolt store.

In most cases, the BindPlane cli can be used on the server
when you are connected over SSH.

Example:

sudo bindplane --config /etc/bindplane/config.yaml get agent

Sudo or root access is required to read the /etc/bindplane/config.yaml.

Procedure

The migration procedure has the following steps:

Export all resources
Stop the service
Backup the single account database and configuration
Enable Multi Account and Configure Authentication
Optional: Configure PostgreSQL
Start the service
Create account
Restore resources
Cleanup
Migrate Agents

Export Resources

Export

While connected to the BindPlane server using SSH, use the get
command with the --export flag to export destinations, sources, processors, and configurations. The order is important, as the resources will be created in the same order they were exported in.

touch migration-resources.yaml

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    get destination -o yaml --export > "migration-resources.yaml"

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    get source -o yaml --export >> "migration-resources.yaml"

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    get processor -o yaml --export >> "migration-resources.yaml"

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    get configuration -o yaml --export >> "migration-resources.yaml"

NOTE: If the the migration-resources.yamlfile exists from a previous migration attempt, move it to a safe
location to prevent overwriting it.

Fill In Sensitive Values

The BindPlane API will not return sensitive values such as passwords and API keys. Therefor you must find and replace (sensitive)in the migration-resources.yaml file. Make sure you update all sources and destinations which have sensitive parameters.

Stop Service

Stop BindPlane in preperation for the migration.

sudo systemctl stop bindplane

Backup Database and Configuration

Rename the database file to bindplane-single-account.db:

sudo mv \
    /var/lib/bindplane/storage/bindplane.db \
    /var/lib/bindplane/storage/bindplane-single-account.db

Copy the configuration file:

sudo cp \
    /etc/bindplane/config.yaml \
    /etc/bindplane/config-single-account.yaml

Enable Multi Account and Configure Authentication

Use the init server command to enable multi account.

sudo BINDPLANE_CONFIG_HOME=/var/lib/bindplane /usr/local/bin/bindplane init server --config /etc/bindplane/config.yaml

When asked to enable MultiAccount, select yes:

Enable MultiAccount
? Enable MultiAccount [? for help] (y/N) Y

When asked to select an "authentication method", select the authentication backend you would like to use.

? Choose an authentication method.  [Use arrows to move, type to filter]
> Single User
  LDAP
  Active Directory

When coming from BindPlane Open Source, you will have been using "Single User" system authentication (basic auth). BindPlane OP Enterprise support LDAP and Active Directory as an alternative to System authentication. See the authentication documentation for detailed information.

All other prompts can remain using their default values, which were
configured during the initial installation.

Configure PostgreSQL

PostgreSQL is an optional storage backend alternative to the default Bolt Store backend. Bolt store is highly performant and recommended for single instance BindPlane OP. Migrations to PostgreSQL can be performed at a later time.

Using your text editor, open /etc/bindplane/config.yaml.

sudo vim /etc/bindplane/config.yaml

Find the store section and update the store.type and store.postgres sections.

store:
  type: postgres
  maxEvents: 100
  bbolt:
    path: /var/lib/bindplane/storage/bindplane.db
  postgres:
    host: 127.0.0.1
    port: "5432"
    database: bindplane
    sslmode: disable
    maxConnections: 100
    username: database-user
    password: database-password

The following should be true

store.type is set to postgres
postgres.host is set to the hostname or ip address of your Postgres server
postgres.port is set to the port of your Postgres server
postgres.database is set to the name of the database BindPlane should use
postgres.sslmode is set to the ssl mode of your Postgres server
postgres.username is set to the username that BindPlane should use to authenticate to Postgres
postgres.password is set to the password that BindPlane should use to authenticate to Postgres

Start Service

Start BindPlane in multi account mode for the first time.

sudo systemctl start bindplane

Create Account

Use the create account command to create an account. In this example,
the account name is migration. Replace the account name with
your desired name.

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    create account migration

Once the account is created, note it's ID:

sudo bindplane \
    --config "/etc/bindplane/config.yaml" \
    get account

Restore Resources

While connected to the BindPlane server using SSH, use the apply
command to import the previously exported resources. This example uses
the account name migration which has the ID 01H6ERPCPB49TSNXA2KHB87XY1.
Replace the ID with the ID of the account created in the previous step.

If using System authentication, the --config flag is sufficient for applying resources.

sudo bindplane \
    --config /etc/bindplane/config.yaml \
    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
    apply -f  migration-resources.yaml

If using LDAP or Active Directory, set the --username and --password flags using your username and password.

sudo bindplane \
    --username "ldap-user" \
    --password "ldap-pass" \
    --config /etc/bindplane/config.yaml \
    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
    apply -f  migration-resources.yaml

Cleanup

When you are satisfied with the migration, cleanup the migration
yaml file. This file could contain sensitive information such as
credentials. It is important to remove it from your user's working
directory.

rm -f migration-resources.yaml

Optionally cleanup the single account configuration and database.

sudo rm -f /etc/bindplane/config-single-account.yaml
sudo rm -f /var/lib/bindplane/storage/bindplane-single-account.db

Migrate Agents

Previously connected agents will need to be updated with the new account's secret key. Follow the Migrate Agents documentation.

Frequently Asked Questions

Can I migrate to a different system?

Yes, migrating to a different BindPlane OP server is supported. Make sure the target system is configured correctly and contains the account you want to migrate to.

When running the bindplane apply command, pass the following flags instead of the --config flag

--remote-url, --username, --password

Example:

sudo bindplane \
    --remote-url "http://192.168.1.10:3001" \
    --username "user" \
    --password "password" \
    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
    apply -f  migration-resources.yaml

Replace the values for remote url, username, and password with the correct values for your target server.

Where should PostgreSQL be Installed?

It is recommended to install PostgresSQL on a dedicated instance, however, Postgres and BindPlane server can coexist on the same system.