Configure CloudBees CD/RO to use an alternate database

If you deselected the “database” check box during installation, you cannot log into CloudBees CD/RO until you set up a database configuration pointing to an external database. a CloudBees CD/RO enterprise license is required; for details, refer to Configure an external database. You can change the database configuration through the CloudBees CD/RO web interface or the CloudBees CD/RO command-line tool.

To change the database configuration in a CloudBees CD/RO cluster, you must reset CloudBees CD/RO to single-server mode beforehand. For details, see Running a Cluster in Single-Server Mode.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

Set the Database with the Web Interface

Use these instructions to use the CloudBees CD/RO web UI to set the external database.

Open the Database configuration page using one of the following methods:
- From the Deploy UI: browse to https://<cloudbees-flow-server>/flow/, and then from the main menu, click Administration > Configurations > Database configuration.
- From the Automation Platform UI: browse to https://<cloudbees-flow-server>/commander/, and then from the main menu, click Administration > Database configuration.

Complete the menus and fields in the Database configuration screen as follows.

Menu or Field Description

Database type

Database server type. Choose Built-in (MariaDB), MySQL, Oracle, PostgreSQL, or Microsoft SQL Server.

The Built-in (MariaDB) option is supported only for the built-in database that is installed by CloudBees CD/RO. Any other MariaDB database is not supported; that is, you cannot install another MariaDB instance and use it with CloudBees CD/RO. Also, changing the database configuration options (such as the database name, host name, and credentials) to use any other database such as MySQL when using the Built-in (MariaDB) option is not supported.

Database name

Database instance name. The default name is commander.

Host name

Host name of your database server. You can enter either the host name or the IP address of the server.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

Port

Port on which the database server is listening. The default is 3306.

Username

Username that the CloudBees CD/RO server will use to access the database on the database server.

Password

Password for the database user that you specified.

Retype password

Confirm the password for the database user that you specified.

Click Save and restart server.
Confirm your changes and restart the CloudBees CD/RO server by selecting OK.

Set the database from a command line

This section contains topics related to setting an alternate database for CloudBees CD/RO through a command line.

SQL server authentication
Set the database with ectool
setDatabaseConfiguration command examples
Configure CloudBees CD/RO server on Windows to use Active Directory SSO authentication
Configure CloudBees CD/RO server on Linux to use Windows Active Directory SSO authentication
setDatabaseConfiguration command options

SQL server authentication

SQL Server supports two types of user authentication:

SQL Server Authentication
Windows Authentication

You must find out from your DBA which authentication type is required for the CloudBees CD/RO user because, the authentication type influences how information is provided in the ectool command setDatabaseConfiguration. Refer to setDatabaseConfiguration command examples for example command syntax.

Set the database with ectool

You use the ectool setDatabaseConfiguration command to change the database configuration from the command line.

Determine if your database is SQL Server. The type of user authentication used by the database impacts the syntax of the setDatabaseConfiguration command that you use in this procedure.

(CloudBees CD/RO 5.0 and later) Set the database configuration based on the type of user authentication used by the database:

For SQL server authentication or a SQL Server with NTLM login, enter
```
setDatabaseConfiguration <--options>▼
```
where ←-options> are the options that you specify based on the type of user authentication.

For a SQL server with the SSO login on Windows, refer to Configure CloudBees CD/RO server on Windows to use Active Directory SSO authentication.

After you change the CloudBees CD/RO database configuration, the server attempts to connect to the database to do the initial schema setup.

Do not restart the CloudBees CD/RO server at this time. (You should restart the server only if it was already connected to a built-in or external database and the ectool setDatabaseConfiguration command has been used to connect the server to an entirely new database.)

Enter the following command and wait for the output:
```
ectool --server localhost --timeout 900 getServerStatus --block 1 --serverStateOnly 1▼
```
This command runs for 900 seconds (15 minutes), or until Commander finishes creating all the schema objects, or until getServerStatus displays either bootstrap or running.

If the output says bootstrap, enter the command again until it says running.

The commander.log file shows commanderServer is running as in the following snippet:

2016-02-10T19:19:06.582 | 10.0.2.206 | INFO | bootstrap |  |  | ServerStatus | commanderServer is running▼

Failing to wait and restarting Commander while it is creating schema objects will cause it to fail to start (during the next manual start) with an error:

2016-09-07T15:08:55.825 | DEBUG | bootstrap |  |  | upgradeData | OperationInvoker | Exception: InvalidSchema: Unable to validate the database schema: could not extract ResultSet 2016-09-07T15:08:55.831 | ERROR | bootstrap  |  |  |  | BootstrapCommanderServerImpl | Unable to validate the database schema: could not extract ResultSetcom.electriccloud.errors.EcException: Unable to validate the database schema: could not extract ResultSetat com.electriccloud.errors.EcException.create(EcException.java:165)at com.electriccloud.errors.EcExceptionBuilder.build(EcExceptionBuilder.java:34)at com.electriccloud.upgrade.UpgradeManagerImpl.doDataMaintenance(UpgradeManagerImpl.java:672)at com.electriccloud.upgrade.UpgradeDataOperation.perform(UpgradeDataOperation.java:50)at com.electriccloud.upgrade.UpgradeDataOperation.perform(UpgradeDataOperation.java:26)▼

Use getServerStatus to look for problems logging into the database or creating the schema. This command shows log prompts from the server bootstrap process.

Before the server is completely up, getServerStatus does not require a login session, but after the server is up, it does. Thus, if you enter the ` getServerStatus` call and get a “session expired” error, the server is up.

setDatabaseConfiguration command examples

Following are examples of how to use the setDatabaseConfiguration command.

SQL Server Authentication:

ectool setDatabaseConfiguration --databaseType sqlserver
--databaseName commander --hostName localhost --port 1433
--userName commander --password commander▼

The --userName and --password options must be included in the setDatabaseConfiguration command.

SQL Server with NTLM login:

ectool setDatabaseConfiguration --databaseType sqlserver --databaseName commander --hostName localhost --port 1433 --userName \commander@example.com --password commander▼

The username must include the domain name. For example, user@example.com or domain\user.

Configure CloudBees CD/RO server on Windows to use Active Directory SSO authentication

Use these steps to configure CloudBees CD/RO to use SSO authentication on Windows platform.

Download the Microsoft JDBC 9.2 authentication driver DLL, mssql-jdbc_auth-9.2.1.x64.dll zip file.

Configure the database connection with a custom database URL that sets the integratedSecurity property for the Microsoft JDBC driver via ectool.

ectool setDatabaseConfiguration --databaseType sqlserver --hostName sqlserver.mydomain.com --port 1433 --databaseName commander --customDatabaseUrl “jdbc:sqlserver://sqlserver.mydomain.com:1433;databaseName=commander;applicationName={CloudBees CD};selectMethod=direct;statementPoolingCacheSize=500;disableStatementPooling=false;integratedSecurity=true”▼

Copy the .dll file from step 1 to the directory C:/Program Files/CloudBees/Software Delivery Automation.
Restart CloudBees CD/RO to apply changes.

Configure CloudBees CD/RO server on Linux to use Windows Active Directory SSO authentication

Use these steps to configure CloudBees CD/RO to use SSO authentication on Linux platform.

Execute the Microsoft instructions to configure Kerberos.

Configure the database connection with a custom database URL that sets the integratedSecurity property for the Microsoft JDBC driver via ectool.

jdbc:sqlserver://sqlserver.mydomain.com:1433;databaseName=commander;applicationName={CloudBees CD};selectMethod=direct;statementPoolingCacheSize=500;disableStatementPooling=false;integratedSecurity=true;authenticationScheme=JavaKerberos”▼

Restart CloudBees CD/RO to apply changes.

setDatabaseConfiguration command options

The following options are available for use with the ectool command setDatabaseConfiguration. The option command syntax is:

setDatabaseConfiguration▼

[--databaseType <mysql|postgresql|sqlserver|Oracle|builtin>]
[--databaseName <database name>]
[--hostName <host name>]
[--ignorePasskeyMismatch <Boolean flag>]
[--ignoreServerMismatch <Boolean flag>]
[--password <password>]
[--port <port number>]
[--preserveSessions <Boolean flag>]
[--userName <user name>]
[--customDatabaseDialect <custom database dialect>]
[--customDatabaseDriver <custom database driver>]
[--customDatabaseUrl <custom database URL>]▼

The following table describes the command options:

Option Description

databaseType

Selects the database type—supported options are mysql|postgresql|sqlserver|Oracle|builtin

The builtin option is supported only for the built-in MariaDB database that is installed by CloudBees CD/RO. Any other MariaDB database is not supported; that is, you cannot install another MariaDB instance and use it with CloudBees CD/RO. Also, changing the database configuration options (such as the database name, host name, and credentials) to use any other database such as MySQL when using the builtin option is not supported.

databaseName

The name of your alternate database—this is not the host name, but the name the DBA gave the database object.

hostName

The host name where your database is running

ignorePasskeyMismatch

< Boolean flag - 0|1|true|false > - If the server is started with a different passkey, ignore the mismatch if “true”.

This action discards all saved passwords.

ignoreServerMismatch

< Boolean flag - 0|1|true|false > - If the server is started on a different host than where the server previously started, ignore the mismatch if “true”.

port

The port number used by the database Server—if omitted, port 1433 is used

preserveSessions

< Boolean flag - 0|1|true|false > - If ignoring a server mismatch, default behavior invalidates all sessions. Setting this flag to “true” saves all sessions, allowing the server to reconnect to running jobs. This option is used in combination with ignoreServerMismatch.

userName

The username to use when connecting to the database

password

The password to use to connect to the database

customDatabaseDialect

Internal option—use only at the request of CloudBees support

customDatabaseDriver

Internal option—use only at the request of CloudBees support

customDatabaseUrl

Internal option—use only at the request of CloudBees support

Enabling Full Database URL Control

Go to the database.properties file.
Add the explicit connect string to that property.