diff --git a/_docs/latest/databases/encrypting-details-at-rest.md b/_docs/latest/databases/encrypting-details-at-rest.md index a4536bfd43..f2565b7c7f 100644 --- a/_docs/latest/databases/encrypting-details-at-rest.md +++ b/_docs/latest/databases/encrypting-details-at-rest.md @@ -38,11 +38,24 @@ Metabase stores connection information for the various databases you add in the MB_ENCRYPTION_SECRET_KEY="IYqrSi5QDthvFWe4/WdAxhnra5DZC3RKx3ZSrOJDKsM=" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar ``` -Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. To encrypt existing connections, see the next section. +Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. If you set the key on a new Metabase, that's all you need to do. To encrypt an existing Metabase, see the next section. -## Encrypting an existing connection +## Encrypting an existing Metabase -If you added databases before setting the `MB_ENCRYPTION_SECRET_KEY` value, you can encrypt the connection details by going to each one of those databases in **Admin** > **Databases** and clicking on the **Save** button. Existing databases with unencrypted details will continue to work normally. +If you're adding an encryption key to a Metabase that already has data, you need to encrypt that data once with the `enable-encryption` command. Metabase won't start while `MB_ENCRYPTION_SECRET_KEY` is set but the application database isn't encrypted with it; it never encrypts existing data on its own. + +1. We recommend that you [backup](../installation-and-operation/backing-up-metabase-application-data) your data before enabling encryption. +2. Stop running your Metabase app. +3. Run the CLI command `enable-encryption` with the key set as `MB_ENCRYPTION_SECRET_KEY`. +4. Start Metabase with the same `MB_ENCRYPTION_SECRET_KEY`. + +### Example command for enabling encryption + +``` +MB_ENCRYPTION_SECRET_KEY=your-key java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar enable-encryption +``` + +If Metabase reports that the database isn't encrypted but you didn't just add the key, don't run `enable-encryption`: someone has changed the application database directly. Restore it from a backup. (A wrong key is reported separately, as a key mismatch.) ## Rotating an encryption key diff --git a/_docs/latest/installation-and-operation/commands.md b/_docs/latest/installation-and-operation/commands.md index 287000f0bc..c4efe7983a 100644 --- a/_docs/latest/installation-and-operation/commands.md +++ b/_docs/latest/installation-and-operation/commands.md @@ -58,6 +58,10 @@ Options: - `-k, --keep-existing` - Do not delete target H2 file if it exists. - `-p, --dump-plaintext` - Do not encrypt dumped contents. +## `enable-encryption` + +Encrypts data in the metabase database with the key in the MB_ENCRYPTION_SECRET_KEY environment variable. Run this once, with Metabase stopped, after adding the key to an existing instance: Metabase refuses to start while the key is set but the database is not encrypted with it. + ## `environment-variables-documentation` Generates a markdown file containing documentation for environment variables relevant to configuring Metabase. The command only includes environment variables registered as defsettings. For a full list of environment variables, see https://www.metabase.com/docs/latest/configuring-metabase/environment-variables. diff --git a/_docs/v0.62/databases/encrypting-details-at-rest.md b/_docs/v0.62/databases/encrypting-details-at-rest.md index 40afb0eb6a..f8c71d4e41 100644 --- a/_docs/v0.62/databases/encrypting-details-at-rest.md +++ b/_docs/v0.62/databases/encrypting-details-at-rest.md @@ -36,11 +36,24 @@ Metabase stores connection information for the various databases you add in the MB_ENCRYPTION_SECRET_KEY="IYqrSi5QDthvFWe4/WdAxhnra5DZC3RKx3ZSrOJDKsM=" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar ``` -Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. To encrypt existing connections, see the next section. +Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. If you set the key on a new Metabase, that's all you need to do. To encrypt an existing Metabase, see the next section. -## Encrypting an existing connection +## Encrypting an existing Metabase -If you added databases before setting the `MB_ENCRYPTION_SECRET_KEY` value, you can encrypt the connection details by going to each one of those databases in **Admin** > **Databases** and clicking on the **Save** button. Existing databases with unencrypted details will continue to work normally. +If you're adding an encryption key to a Metabase that already has data, you need to encrypt that data once with the `enable-encryption` command. Metabase won't start while `MB_ENCRYPTION_SECRET_KEY` is set but the application database isn't encrypted with it; it never encrypts existing data on its own. + +1. We recommend that you [backup](../installation-and-operation/backing-up-metabase-application-data) your data before enabling encryption. +2. Stop running your Metabase app. +3. Run the CLI command `enable-encryption` with the key set as `MB_ENCRYPTION_SECRET_KEY`. +4. Start Metabase with the same `MB_ENCRYPTION_SECRET_KEY`. + +### Example command for enabling encryption + +``` +MB_ENCRYPTION_SECRET_KEY=your-key java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar enable-encryption +``` + +If Metabase reports that the database isn't encrypted but you didn't just add the key, don't run `enable-encryption`: someone has changed the application database directly. Restore it from a backup. (A wrong key is reported separately, as a key mismatch.) ## Rotating an encryption key diff --git a/_docs/v0.62/installation-and-operation/commands.md b/_docs/v0.62/installation-and-operation/commands.md index bf6d5e17a5..b6b4c829a6 100644 --- a/_docs/v0.62/installation-and-operation/commands.md +++ b/_docs/v0.62/installation-and-operation/commands.md @@ -54,6 +54,10 @@ Options: - `-k, --keep-existing` - Do not delete target H2 file if it exists. - `-p, --dump-plaintext` - Do not encrypt dumped contents. +## `enable-encryption` + +Encrypts data in the metabase database with the key in the MB_ENCRYPTION_SECRET_KEY environment variable. Run this once, with Metabase stopped, after adding the key to an existing instance: Metabase refuses to start while the key is set but the database is not encrypted with it. + ## `environment-variables-documentation` Generates a markdown file containing documentation for environment variables relevant to configuring Metabase. The command only includes environment variables registered as defsettings. For a full list of environment variables, see https://www.metabase.com/docs/latest/configuring-metabase/environment-variables. diff --git a/_docs/v0.63/databases/encrypting-details-at-rest.md b/_docs/v0.63/databases/encrypting-details-at-rest.md index 6e2c542941..74be79d936 100644 --- a/_docs/v0.63/databases/encrypting-details-at-rest.md +++ b/_docs/v0.63/databases/encrypting-details-at-rest.md @@ -36,11 +36,24 @@ Metabase stores connection information for the various databases you add in the MB_ENCRYPTION_SECRET_KEY="IYqrSi5QDthvFWe4/WdAxhnra5DZC3RKx3ZSrOJDKsM=" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar ``` -Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. To encrypt existing connections, see the next section. +Once you set the `MB_ENCRYPTION_SECRET_KEY` value, Metabase will automatically encrypt and store the connection details for each new database that you add. If you set the key on a new Metabase, that's all you need to do. To encrypt an existing Metabase, see the next section. -## Encrypting an existing connection +## Encrypting an existing Metabase -If you added databases before setting the `MB_ENCRYPTION_SECRET_KEY` value, you can encrypt the connection details by going to each one of those databases in **Admin** > **Databases** and clicking on the **Save** button. Existing databases with unencrypted details will continue to work normally. +If you're adding an encryption key to a Metabase that already has data, you need to encrypt that data once with the `enable-encryption` command. Metabase won't start while `MB_ENCRYPTION_SECRET_KEY` is set but the application database isn't encrypted with it; it never encrypts existing data on its own. + +1. We recommend that you [backup](../installation-and-operation/backing-up-metabase-application-data) your data before enabling encryption. +2. Stop running your Metabase app. +3. Run the CLI command `enable-encryption` with the key set as `MB_ENCRYPTION_SECRET_KEY`. +4. Start Metabase with the same `MB_ENCRYPTION_SECRET_KEY`. + +### Example command for enabling encryption + +``` +MB_ENCRYPTION_SECRET_KEY=your-key java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar enable-encryption +``` + +If Metabase reports that the database isn't encrypted but you didn't just add the key, don't run `enable-encryption`: someone has changed the application database directly. Restore it from a backup. (A wrong key is reported separately, as a key mismatch.) ## Rotating an encryption key diff --git a/_docs/v0.63/installation-and-operation/commands.md b/_docs/v0.63/installation-and-operation/commands.md index 7be5aef076..b85b5e3d0a 100644 --- a/_docs/v0.63/installation-and-operation/commands.md +++ b/_docs/v0.63/installation-and-operation/commands.md @@ -54,6 +54,10 @@ Options: - `-k, --keep-existing` - Do not delete target H2 file if it exists. - `-p, --dump-plaintext` - Do not encrypt dumped contents. +## `enable-encryption` + +Encrypts data in the metabase database with the key in the MB_ENCRYPTION_SECRET_KEY environment variable. Run this once, with Metabase stopped, after adding the key to an existing instance: Metabase refuses to start while the key is set but the database is not encrypted with it. + ## `environment-variables-documentation` Generates a markdown file containing documentation for environment variables relevant to configuring Metabase. The command only includes environment variables registered as defsettings. For a full list of environment variables, see https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.