Add databases through the headless installer

Use the headless installer to onboard and configure multiple databases at once. The SolarWinds Observability SaaS headless installer for databases can onboard, update, and delete databases in SolarWinds Observability SaaS using specified input files. The headless installer connects to the SolarWinds Observability SaaS GraphQL Public API and issues commands to delete, onboard, or update your databases in SolarWinds Observability SaaS. See Public API.

Before using the headless installer

To onboard, update, or delete multiple databases with the headless installer, you need the following.

• A registered Agent. See Add a host for instructions.

• An API Access token. See API tokens for instructions.

• JSON files that define the SolarWinds Observability SaaS GraphQL endpoint, API Access token, and database settings. See -Onboard-databases, and update-databases below.

The headless installer for SolarWinds Observability SaaS uses the Agent to install database plugins through JSON inputs that specify the database endpoint, the Full access API token, and other database instance entity details.

Headless installer user permissions

The SolarWinds Observability SaaS user that downloads and executes the headless installer binary file needs to have execute privileges.

Download the headless installer

After you have set up your Agent, and API Access token, you can download the headless installer binary file. Download the headless installer here.

Headless installer command options

The database headless installer can be used to delete, update, or onboard multiple databases in SolarWinds Observability SaaS. You can issue multiple commands at the same time. The following options are available for the SolarWinds Observability SaaS database headless installer.

-swoparams

The -swoparams is used to list the path of a JSON file containing the API Access apiToken and the SolarWinds Observability SaaS GraphQL endpoint according to region. This will always be the first part of any command you issue to the SolarWinds Observability SaaS GraphQL API endpoint. For example:

./dbo-headless-installer -swoparams=bin/inputs/prodPublicApiParams.json -onboard-databases=bin/inputs/prodPluginsOnTwoUams.json

The JSON file referenced by -swoparams needs the following format.

{
"swoUrl" : "https://api.xx-yy.cloud.solarwinds.com/graphql",
"apiToken": "<TOKEN>"
}

-delete-db-list

The -delete-db-list command is used to list the path of a JSON file containing the list of database entities to be deleted. For example:

./dbo-headless-installer -swoparams=bin/inputs/prodPublicApiParams.json -delete-db-list=bin/onboarded.json.

The sample file that is generated during onboarding has the following format.

{<entityID>:<name>} e.g.
{
"e-1719678930983378944": "dbo headless installer demo::mongodb profiler listening on 10.0.2.2:27018",
"e-1719678939370647552": "dbo headless installer demo::mongodb slow-log listening on 10.0.2.2:27018",
}

-onboarded-list-out

The -onboarded-list-out command lists the path of a file where the headless installer would write the listed entityIDs and the names of onboarded databases. The output file is in JSON and can be used later for use with the -delete-db-list command.

If this command is not specified, the list of onboarded database entities will output to a log and a new file formatted as onboarded-<TIME> in the current working directory.

-onboard-databases

The -onboard-databases command lists the path of a json file containing the list of SolarWinds Observability SaaS Agent IDs and the list of databases that need to be onboarded. For example:

./dbo-headless-installer -swoparams=bin/inputs/prodPublicApiParams.json -onboard-databases=inputs/prodPublicApiOnboardParam.json

The JSON file referenced by -onboard-databases needs the following format.

[
	{
		"agentID": "c7884c9d-711a-4836-8245-c891a06d9e86", 
		"dbAgents": [
		     {
			"databaseType": "mongo", 
			"name": "demo::mongodb profiler on test-host listening on 10.0.2.2:27018", 
			"host": "10.0.2.2", 
			"port": "27018", 
			"user": "myUser", 
			"password": "<password>", 
			"dbName": "<DB name>", 
			"packetCaptureEnabled": false, 
			"metricsCaptureMethod": "profiler", 
			"metricsAgentConfigFile": path of a json file specifying advanced config options for metrics agent,
			"snifferAgentConfigFile": path of a json file specifying advanced config options for packet capture/query agent,
			"bindings" : "0.0.0.0:6379,[::]:6379", 
			"metricsagentoptions": {"key":"value", "key2":"value2"} 
			}
		]
	}
]

The following options are configurable for the -onboard-databases command.

Option	Description
"agentID"	The SolarWinds Observability SaaS Agent ID where the database observability plugin will be installed. All agentIDs specified in the -onboard-database command must be in the same SolarWinds Observability SaaS organization as the specified apiToken.
"databaseType"	The type of database you want to configure mongo/mysql/pgsql/mssql/redis.
"name"	The name that will be used for the database instance entity in SolarWinds Observability SaaS.
"host"	The host name for the database.
"port"	The port number of the database.
"user"	The username for the database. User can be left blank for Redis databases.
"password"	The password for the database.
"dbName"	The database name on the server. dbName is required for PostgreSQL databases and optional for SQL Server databases. All other database types ignore dbName.
"packetCaptureEnabled"	Set to true to enable packet sniffing. Set to false to disable packet sniffing. This option is set to false by default and is ignored for SQL Server and Redis database types.
"metricsCaptureMethod"	Used only in case of off-host for mongoDB (values profiler/slow-log). This option can be set to profiler or slow-log. This option is ignored if packetCaptureEnabled:true.
"metricsAgentConfigFile"	Enter the path of a JSON file specifying advanced configuration options for metrics agent.
"snifferAgentConfigFile"	Enter the path of a JSON file specifying advanced configuration options for packet capture/query agent.
"bindings"	Comma separated values specifying bindings. This option is used only for packet capture deployments and is auto generated if not provided. Bindings are ignored for SQL Server databases, and other databases that are deployed with packetCaptureEnabled:false.
"metricsagentoptions"	Map of key:values strings which specify options for the metrics agent. All the ssl options are not supported for on-host(packet capture) deployments. Database type metric agent options MongoDB sslEnabled : true/false sslCAFile - The location of the root certificate file. The file must contain PEM encoded data, and all files specified above need to be readable by the metricsagent. sslKeyFile - Key file location. The file must contain PEM encoded data. SQL Server sslCAFile - The location of the root certificate file. The file must contain PEM encoded data, and all files specified above need to be readable by the metricsagent. sslMode - Valid values for sslMode are: require - Always SSL (skip verification) verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA) MySQL sslEnabled : true/false sslCAFile - The location of the root certificate file. The file must contain PEM encoded data, and all files specified above need to be readable by the metricsagent. sslKeyFile - Key file location. The file must contain PEM encoded data. sslCertFile - Cert file location. The file must contain PEM encoded data. PostgreSQL sslCAFile - The location of the root certificate file. The file must contain PEM encoded data, and all files specified above need to be readable by the metricsagent. sslKeyFile - Key file location. The file must contain PEM encoded data. sslCertFile - Cert file location. The file must contain PEM encoded data. sslMode - This is option is required to enable ssl. Valid values for sslMode for pgsql are: require - Always SSL (skip verification) verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA) verify-full - Always SSL ( verify that the server certificate is issued by a trusted CA and that the server hostname matches that in the certificate.)

-update-databases

The -update-databases command lists the path of a JSON file containing the list of Database Entity IDs along with the details that will be updated. For example:

./dbo-headless-installer -swoparams=bin/inputs/prodPublicApiParams.json -update-databases=inputs/prodPublicApiUpdateParam.json.

The JSON file referenced by -update-databases needs the following format.

[
	{
		"databaseID": "entityID for the SWO Database Instance to be updated, e.g. e-1692609227148427264",
		"name": "demo::mongodb profiler on test-host listening on 10.0.2.2:27018", 
		"host": "10.0.2.2", 
		"port": "27018", 
		"user": "myUser", 
		"password": "<password>", 
		"dbName": "<DB name>", 
		"metricsAgentConfigFile": path of a json file specifying advanced config options for metrics agent,
		"snifferAgentConfigFile": path of a json file specifying advanced config options for packet capture/query agent,
	}
]

The following options are configurable for the -update-databases command.

Option	Description
"agentID"	The SolarWinds Observability SaaSAgent ID where the database observability plugin will be installed. All agentIDs specified in the -onboard-database command must be in the same SolarWinds Observability SaaS organization as the specified apiToken.
"databaseType"	The type of database you want to configure mongo/mysql/pgsql/mssql/redis.
"name"	The name that will be used for the database instance entity in SolarWinds Observability SaaS.
"host"	The host name for the database.
"port"	The port number of the database.
"user"	The username for the database. User can be left blank for Redis databases.
"password"	The password for the database.
"dbName"	The database name on the server. dbName is required for PostgreSQL databases and optional for SQL Server databases. All other database types ignore dbName.
"packetCaptureEnabled"	Set to true to enable packet sniffing. Set to false to disable packet sniffing. This option is set to false by default and is ignored for SQL Server and Redis database types.
"metricsCaptureMethod"	Used only in case of off-host for mongoDB (values profiler/slow-log). This option can be set to profiler or slow-log. This option is ignored if packetCaptureEnabled:true.
"metricsAgentConfigFile"	Enter the path of a JSON file specifying advanced configuration options for metrics agent. This is optional.
"snifferAgentConfigFile"	Enter the path of a JSON file specifying advanced configuration options for packet capture/query agent. This is optional.
"bindings"	Comma separated values specifying bindings. This option is used only for packet capture deployments and is auto generated if not provided. Bindings are ignored for SQL Server databases, and other databases that are deployed with packetCaptureEnabled:false.

Add databases with the headless installer

1. Open an administrator command prompt.

2. Connect to the SolarWinds Observability SaaS GraphQL API. The API can be accessed at the URL https://api.xx-yy.cloud.solarwinds.com/graphql, where xx-yy matches your organization's data center, see Data centers and endpoint URIs.

3. Enter the -swoparams and -onboard-databases command to reference your API Access token, GraphQL API endpoint, and database configuration(s) to be updated through JSON.

   Windows Example

   ./dbo-headless-installer -swoparams=C:/users/dbouser/json/inputs/prodPublicApiParams.json 
   -onboard-databases=C:/users/dbouser/json/inputs/inputs/prodPublicApiOnboardParam.json

   Linux Example

   ./dbo-headless-installer -swoparams=/home/dbouser/prodPublicApiParams.json 
   -onboard-databases=/home/dbouser/prodPublicApiOnboardParam.json

4. In SolarWinds Observability SaaS go to Settings > Agents and click on the desired Agent to see the databases onboarded.

Update databases with the headless installer

1. Open an administrator command prompt.

2. Connect to the SolarWinds Observability SaaS GraphQL API. The API can be accessed at the URL https://api.xx-yy.cloud.solarwinds.com/graphql, where xx-yy matches your organization's data center, see Data centers and endpoint URIs.

3. Enter the -swoparams and - -update-databases command to reference your API Access token, GraphQL API endpoint, and database configuration(s) to be updated through JSON.

   Windows Example

   ./dbo-headless-installer -swoparams=C:/users/dbouser/json/inputs/prodPublicApiParams.json
   -update-databases=C:/users/dbouser/json/inputs/prodPublicApiUpdateParam.json/

   Linux Example

   ./dbo-headless-installer -swoparams=/home/dbouser/prodPublicApiParams.json
   -update-databases=/home/dbouser/prodPublicApiUpdateParam.json

4. In SolarWinds Observability SaaS go to Settings > Agents and click on the desired Agent to see the databases onboarded.

Delete databases with the headless installer

1. Open an administrator command prompt.

2. Connect to the SolarWinds Observability SaaS GraphQL API. The API can be accessed at the URL https://api.xx-yy.cloud.solarwinds.com/graphql, where xx-yy matches your organization's data center, see Data centers and endpoint URIs.

3. Enter the -swoparams and the -delete-db-list command to reference your API Access token, and GraphQL API endpoint, and database configuration(s) to be deleted through JSON.

   Windows Example

   ./dbo-headless-installer -swoparams=C:/users/dbouser/json/inputs/prodPublicApiParams.json
   -delete-db-list=C:/users/dbouser/json/inputs/prodPublicApiDeleteParam.json/  

   Linux Example

   ./dbo-headless-installer -swoparams=/home/dbouser/prodPublicApiParams.json
   -delete-db-list=/home/dbouser/prodPublicApiDeleteParam.json/