Single Account to Multi Account

How to migrate from Single Account to Multi Account

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 supports user invitations 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:

bash
1sudo 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:

  1. Export all resources
  2. Stop the service
  3. Backup the single account database and configuration
  4. Enable Multi-Account and Configure Authentication
  5. Optional: Configure PostgreSQL
  6. Start the service
  7. Create account
  8. Restore resources
  9. Cleanup
  10. 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.

bash
1touch migration-resources.yaml
2
3sudo bindplane \
4    --config "/etc/bindplane/config.yaml" \
5    get destination -o yaml --export > "migration-resources.yaml"
6
7sudo bindplane \
8    --config "/etc/bindplane/config.yaml" \
9    get source -o yaml --export >> "migration-resources.yaml"
10
11sudo bindplane \
12    --config "/etc/bindplane/config.yaml" \
13    get processor -o yaml --export >> "migration-resources.yaml"
14
15sudo bindplane \
16    --config "/etc/bindplane/config.yaml" \
17    get configuration -o yaml --export >> "migration-resources.yaml"

note

If the the migration-resources.yaml file 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. Therefore 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 preparation for the migration.

bash
1sudo systemctl stop bindplane

Backup Database and Configuration

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

bash
1sudo mv \
2    /var/lib/bindplane/storage/bindplane.db \
3    /var/lib/bindplane/storage/bindplane-single-account.db

Copy the configuration file:

bash
1sudo cp \
2    /etc/bindplane/config.yaml \
3    /etc/bindplane/config-single-account.yaml

Enable Multi-Account and Configure Authentication

Use the init server command to enable multi-account.

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

When asked to enable MultiAccount, select yes:

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

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

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

When coming from BindPlane Open Source, you will have been using "Single User" system authentication (basic auth). BindPlane OP Enterprise supports 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.

bash
1sudo vim /etc/bindplane/config.yaml

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

yaml
1store:
2  type: postgres
3  maxEvents: 100
4  bbolt:
5    path: /var/lib/bindplane/storage/bindplane.db
6  postgres:
7    host: 127.0.0.1
8    port: '5432'
9    database: bindplane
10    sslmode: disable
11    maxConnections: 100
12    username: database-user
13    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.

bash
1sudo 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.

bash
1sudo bindplane \
2    --config "/etc/bindplane/config.yaml" \
3    create account migration

Once the account is created, note its ID:

bash
1sudo bindplane \
2    --config "/etc/bindplane/config.yaml" \
3    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.

bash
1sudo bindplane \
2    --config /etc/bindplane/config.yaml \
3    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
4    apply -f  migration-resources.yaml

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

bash
1sudo bindplane \
2    --username "ldap-user" \
3    --password "ldap-pass" \
4    --config /etc/bindplane/config.yaml \
5    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
6    apply -f  migration-resources.yaml

Clean up

When you are satisfied with the migration, clean up 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.

bash
1rm -f migration-resources.yaml

Optionally clean up the single account configuration and database.

bash
1sudo rm -f /etc/bindplane/config-single-account.yaml
2sudo 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:

bash
1sudo bindplane \
2    --remote-url "http://192.168.1.10:3001" \
3    --username "user" \
4    --password "password" \
5    --account "01H6PK5SXWBJG77ZBNTR0M9ENC" \
6    apply -f  migration-resources.yaml

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

Where should PostgreSQL be Installed?

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