diff --git a/_articles/faqs/hosting-faqs.md b/_articles/faqs/hosting-faqs.md index 71058425..e046b41e 100644 --- a/_articles/faqs/hosting-faqs.md +++ b/_articles/faqs/hosting-faqs.md @@ -6,7 +6,7 @@ featured: true popular: true hidden: false tags: [] -order: 12 +order: 13 --- This article contains Frequently Asked Questions (FAQs) regarding **Self-hosting**. diff --git a/_articles/hosting/environment-variables.md b/_articles/hosting/environment-variables.md index fe7c4234..01ca7cac 100644 --- a/_articles/hosting/environment-variables.md +++ b/_articles/hosting/environment-variables.md @@ -22,6 +22,7 @@ The following variables are among those that already exist in `global.override.e |Variable|Description| |--------|-----------| +|globalSettings__sqlServer__connectionString=|Use this field to [connect to an exernal MSSQL database]({{site.baseurl}}/article/external-db/).| |globalSettings__oidcIdentityClientKey=|A randomly generated OpenID Connect client key. For more information, see [OpenID Documentation](https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse){:target="\_blank"}.| |globalSettings__duo__aKey=|A randomly generated Duo akey. For more information, see [Duo's Documentation](https://duo.com/docs/duoweb#1.-generate-an-akey){:target="\_blank"}.| |globalSettings__yubico__clientId=|Client ID for YubiCloud Validation Service or Self-hosted Yubico Validation Server.

If YubiCloud, get your Client ID and Secret Key [here](https://upgrade.yubico.com/getapikey/){:target="\_blank"}.

If self-hosted, see Optional Variable `globalSettings__yubico__validationUrls`.| diff --git a/_articles/hosting/external-db.md b/_articles/hosting/external-db.md new file mode 100644 index 00000000..24fa6011 --- /dev/null +++ b/_articles/hosting/external-db.md @@ -0,0 +1,42 @@ +--- +layout: article +title: Connect to an External MSSQL Database +categories: [hosting] +featured: false +popular: false +tags: [hosting, database, mssql] +order: 12 +--- + +By default, self-hosted instances of Bitwarden will use a Microsoft SQL Server (MSSQL) database created as a normal part of [installation setup]({{site.baseurl}}/article/install-on-premise), however you configure Bitwarden to use an external MSSQL database. + +{% callout info %} +Currently, self-hosted installations of Bitwarden support **only** MSSQL databases. Stay tuned for future updates on this topic. +{% endcallout %} + +To setup your self-hosted instance with an external database: + +1. Create a new MSSQL database named `vault`. + + {% callout warning %}You **must** use `vault` as your database name. A different database name will cause migration to fail.{% endcallout %} +2. (**Recommended**) Create a dedicated DBO for your `vault` database. +3. As an administrator of your Bitwarden server, open the `global.override.env` file in an editor: + + ``` + nano bwdata/env/global.override.env + ``` +4. Edit the `globalSettings__sqlServer__connectionString=` value for the following information. + + - Replace `"Data Source=tcp:mssql,1443";` with your MSSQL Server name, for example `"Data Source=protocol:server_url,port"`. + - If you created a DBO, replace `User ID=sa;` with your DBO User ID. + - Replace `Password=;` with your DBO or SA password. +5. Save your changes to `global.override.env`. +6. Start Bitwarden (`./bitwarden.sh start`). + +{% comment %} +6. Run `./bitwarden.sh updatedb` to migrate the **database schema**. + + {% callout success %}`updatedb` does not migrate data, it only migrates the database schema. To move existing data to the new database, [restore a backup]({{site.baseurl}}/article/backup-on-premise/#restore-a-nightly-backup) from `./bwdata/mssql/backups`.{% endcallout %} +{% endcomment %} + +Once the above steps are complete, you can test the connection by creating a new user through the Web Vault and querying the external `vault` database for creation of the new user.