Preferred Connect Strings

A Preferred Connect String is a fully qualified connection descriptor that can override Enterprise Manager’s default connection configuration to the database with your preferred connection method. For example, you can create a preferred connect string using the host, port and service name (instead of SID), and specify that to be used for database connections. Preferred Connect Strings are supported for Single Instance, RAC and Pluggable databases.

There are two types of connections that support this configuration:

From the OMS to a target database, used for access to database performance pages and for administration operations: To use a connect string for OMS-to-database connections, you specify an OMS Preferred Connect String (OMSPCS).
Between an agent and a target database, used for metric collections: To use a connect string for agent-to-database connections, you specify an Agent Preferred Connect String (APCS).

The Preferred Connect Strings can be configured using EM console or EM CLI.

The OMS Preferred Connect String option is supported for all versions of Oracle Enterprise Manager 13c Release 5.

This Agent Preferred Connect String option is supported starting with Oracle Enterprise Manager 13c Release 5 Update 15 (13.5.0.15) and the EM agent version 13.5.0.15. The Agent Preferred Connect String is disabled by default. To enable it, run the following command, and restart the OMS:

emctl set property -name oracle.sysman.db.showapcs -value true -sysman_pwd <sysman_password>

Preferred Connect String Configuration Steps

Choose one of the following methods to define the connect strings:

Using the EM Console: From the target's home page menu, go to Target Setup, then Monitoring Configuration.

Here is an example for the RAC (Cluster Database) Instance:

Using EMCLI: Specify the Preferred Connect String using EMCLI, using this format:

OMS Preferred Connect String

emcli modify_target 
    -name=“<target_name>" 
    -type=“<target_type>" 
    -properties="PreferredConnectString:<connect string>" 
    -on_agent

Example:

emcli modify_target     
    -name="database_CDB1_PDB1"
    -type="oracle_pdb"    
    -properties="PreferredConnectString:(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=host1.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=myrac)(INSTANCE_NAME=db231)))"
    -on_agent

Agent Preferred Connect String

emcli modify_target 
    -name=“<target_name>" 
    -type=“<target_type>"
    -properties="AgentPreferredConnectString:<connect string>" 
    -on_agent

Example:

emcli modify_target   
    -name="MyPDB" 
    -type="oracle_pdb"
    -properties="AgentPreferredConnectString: (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = tcp)(HOST = host1.example.com)(PORT = 1522)))(CONNECT_DATA = (SERVICE_NAME = MYPDB)))"
    -on_agent

If you updated the OMS Preferred Connect String, log out and re-log in to the EM Console to update the OMS-database cached connections.

Examples of Using the Preferred Connect Strings

Database Monitoring Using Service Name

By default, Enterprise Manager uses SID for connections to the database. You can use Preferred Connect Strings to have all EM database connections use the Service Names instead of SIDs. This includes OMS-to-database connections as well as Agent-to-database connections.

For single instance databases or RAC instances, specify the connect string using this format:
```
(DESCRIPTION=(ADDRESS=(PROTOCOL=<protocol,tcp/tcps)(HOST=<host name, e.g.
          myhost.example.com)(PORT=<port, e.g.
          1521>))(CONNECT_DATA=(SERVICE_NAME=<service name>)(INSTANCE_NAME=<instance
          name>)))
```
For RAC databases, set the Preferred Connect String for each RAC instance, where the host should be set to the virtual IP of the RAC node.
Monitoring PDBs in a Cluster Database (RAC)

You can use Preferred Connect Strings to monitor a PDB that is open only a preferred subset of RAC instances.

For this configuration, follow the steps below:
1. Create a service for this PDB.
2. Construct a fully qualified connect string that uses the SCAN listener and service for the PDB:
```
(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = tcp)(HOST = <hostname of the scan listener>)(PORT = 1521)))(CONNECT_DATA = (SERVICE_NAME = <service for the PDB)))
```
3. Edit the Monitoring configuration UI for the PDB and specify your constructed connect string as the values for OMS Preferred Connect String and Agent Preferred Connect String
  
  The agent will connect via the SCAN listener to the open PDB on the preferred RAC instance.

Monitoring Using TCPS-based connections with SSL Server DN Match

TCPS offers enhanced levels of security and it can be configured with SSL Domain Name.

Configure the OMS Preferred Connect String with the SSL domain name as follows:

Enable this setup in the OMS by running following command:

emctl set property 
    -sysman_pwd <password> 
    -name oracle.sysman.db.ssl_server_dn_match 
    -value true

Run the following command on the database host to get the host domain name:

orapki wallet display -wallet "<path_to_wallet>" -pwd <wallet_password>

Example output:

Oracle PKI Tool Release 21.0.0.0.0 - Production
Version 21.0.0.0.0
Copyright (c) 2004, 2020, Oracle and/or its affiliates. All rights reserved.Requested Certificates: 
User Certificates:
Subject:        CN=<server_cert_name> <---- This is the HOST DN (CN=<server_cert_name>) you should use in Preferred Connect String
Trusted Certificates: 
Subject:        CN=<client_cert_name>
Subject:        CN=<server_cert_name>

Construct the OMS Preferred Connect String using the certificate name as the SECURITY parameter, as shown:

(DESCRIPTION= (ADDRESS= (PROTOCOL=TCPS) (HOST=<DB_HOST>) (PORT=<TCPS_PORT>)) (CONNECT_DATA= (SID=<DB_SID>)) (SECURITY=(SSL_SERVER_CERT_DN=CN=<server_cert_name>)))

Specify the OMS Preferred Connect String either using the EM Console or EM CLI.

Monitoring Database Targets in Different Subnets

If your OMS cannot have direct connections to the database targets because they are in separate subnets, or in separate data centers, you can use the OMS Preferred Connect String to connect with a proxy server:
```
(DESCRIPTION= (ADDRESS=(HTTPS_PROXY=<proxy name, e.g.sales-proxy) (HTTPS_PROXY_PORT=8080) (PROTOCOL=TCPS) (HOST=<host name>) (PORT=443)) (CONNECT_DATA=(SERVICE_NAME=service1.example.com)))
```
Note:

This feature requires Oracle Enterprise Manager 13c Release 5 Update 15 (13.5.0.15) or higher.