Single Account to Multi Account
How to migrate from Single Account to 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.
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.
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.
1sudo bindplane --config /etc/bindplane/config.yaml get agent
Sudo or root access is required to read the
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
- Migrate Agents
While connected to the BindPlane server using SSH, use the
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.
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"
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
migration-resources.yaml file. Make sure you update all sources and destinations which have sensitive parameters.
Stop BindPlane in preparation for the migration.
1sudo systemctl stop bindplane
Backup Database and Configuration
Rename the database file to
1sudo mv \ 2 /var/lib/bindplane/storage/bindplane.db \ 3 /var/lib/bindplane/storage/bindplane-single-account.db
Copy the configuration file:
1sudo cp \ 2 /etc/bindplane/config.yaml \ 3 /etc/bindplane/config-single-account.yaml
Enable Multi-Account and Configure Authentication
init server command to enable multi-account.
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:
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.
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.
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
1sudo vim /etc/bindplane/config.yaml
store section and update the
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.typeis set to
postgres.hostis set to the hostname or IP address of your Postgres server
postgres.portis set to the port of your Postgres server
postgres.databaseis set to the name of the database BindPlane should use
postgres.sslmodeis set to the ssl mode of your Postgres server
postgres.usernameis set to the username that BindPlane should use to authenticate to Postgres
postgres.passwordis set to the password that BindPlane should use to authenticate to Postgres
Start BindPlane in multi-account mode for the first time.
1sudo systemctl start bindplane
create account command to create an account. In this example,
the account name is
migration. Replace the account name with
your desired name.
1sudo bindplane \ 2 --config "/etc/bindplane/config.yaml" \ 3 create account migration
Once the account is created, note its ID:
1sudo bindplane \ 2 --config "/etc/bindplane/config.yaml" \ 3 get account
While connected to the BindPlane server using SSH, use the
command to import the previously exported resources. This example uses
the account name
migration which has the ID
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.
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
--password flags using your username and password.
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
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
1rm -f migration-resources.yaml
Optionally clean up the single account configuration and database.
1sudo rm -f /etc/bindplane/config-single-account.yaml 2sudo rm -f /var/lib/bindplane/storage/bindplane-single-account.db
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
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.