This chapter provides a complete listing of the Show
6.1 Overview of Local Naming ParametersThe A net service name is an alias mapped to a database network address contained in a connect descriptor. A connect descriptor contains the location of the listener through a protocol address and the service name of the database to which to connect. Clients and database servers (that are clients of other database servers) use the net service name when making a connection with an application. By default, the
Note: On Microsoft Windows, the See Also:
6.2 General Syntax of tnsnames.oraThe basic syntax for a Example 6-1 Basic Format of tnsnames.ora File net_service_name= (DESCRIPTION= In the preceding example, 6.3 Multiple Descriptions in tnsnames.oraA Example 6-2 Net Service Name with Multiple Connect Descriptors in tnsnames.ora net_service_name= (DESCRIPTION_LIST= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=sales.us.example.com))) (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=hr1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=hr2-svr)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=hr.us.example.com)))) Note: Oracle Net Manager does not support the creation of multiple connect descriptors for a net service name when using Oracle Connection Manager. 6.4 Multiple Address Lists in tnsnames.oraThe Example 6-3 Multiple Address Lists in tnsnames.ora net_service_name= (DESCRIPTION= (ADDRESS_LIST= (LOAD_BALANCE=on) (FAILOVER=off) (ADDRESS=( Note:
6.5 Connect-Time Failover and Client Load Balancing with Oracle Connection ManagersWhen a connect descriptor in a Example 6-4 Multiple Oracle Connection Manager Addresses in tnsnames.ora This example illustrates failover of multiple Oracle Connection Manager protocol addresses.
Here, the syntax does the following:
Example 6-5 Client Load Balancing in tnsnames.ora This example illustrates client load balancing among two Oracle Connection Managers and two protocol addresses:
Here, the syntax does the following:
6.6 Connect Descriptor DescriptionsEach connect descriptor is contained within the
6.6.1 DESCRIPTION_LIST
Purpose To define a list of connect descriptors for a particular net service name. Example 6-6 Example
6.6.2 DESCRIPTIONDESCRIPTION networking parameter of the tnsnames.ora file specifies a container for a connect descriptor. Purpose To specify a container for a connect descriptor. Usage Notes When using more than one Example 6-7 Example
6.7 Protocol Address SectionThe protocol address section of the
6.7.1 ADDRESSThe Purpose To specify a single listener protocol address. Usage Notes Put this parameter under either the Example
6.7.2 HTTPS_PROXYLearn to use the Purpose To specify HTTP proxy host name for tunneling TLS client connections. Usage Notes The clients can tunnel secure connections over forward HTTP proxy using HTTP CONNECT method. This helps in accessing the public cloud database service as it eliminates the requirement to open an outbound port on a client side firewall. This parameter is applicable only to the connect descriptors where Successful connection depends on specific proxy configurations. The performance of data transfers depends on proxy capacity. Oracle recommends not to use this feature in production environments where performance is critical. Configuring Oracle Client versions earlier than 18c does not support connections through HTTP proxy. Contact your network administrator to open outbound connections to hosts in the Values HTTP proxy host name that can make an outbound connection to the internet hosts. Example
6.7.3 HTTPS_PROXY_PORTLearn how to use the Purpose To specify forward HTTP proxy host port for tunneling TLS client connections. Usage Notes It forwards the HTTP proxy host port that receives HTTP CONNECT method. This
parameter should be used along with Example
6.7.4 ADDRESS_LISTThe Purpose To define a list of protocol addresses. Usage Notes If there is only one listener protocol address, then Put this parameter either under the Example
6.8 Optional Parameters for Address ListsFor multiple addresses, you can use the optional parameters to configure address lists.
6.8.1 ENABLEPurpose To allow the caller to detect a terminated remote server, typically it takes 2 hours or more to notice. Usage Notes The keepalive feature on the supported TCP transports can be enabled for a net service client by putting Values broken Example net_service_name=
(DESCRIPTION=
(ENABLE=broken)
(ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
Although the preceding example has multiple addresses, the 6.8.2 FAILOVERPurpose To enable or disable connect-time failover for multiple protocol addresses. Usage Notes When you set the parameter to
Put this parameter under the Note: Do not set the Default
Values
Example net_service_name=
(DESCRIPTION=
(FAILOVER=on)
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))) 6.8.3 LOAD_BALANCEPurpose To enable or disable client load balancing for multiple protocol addresses. Usage Notes When you set the parameter to Put this parameter under the Default
Values
Example net_service_name=
(DESCRIPTION=
(LOAD_BALANCE=on)
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) 6.8.4 RECV_BUF_SIZEUse the Purpose To specify, in bytes, the buffer space for receive operations of sessions. Usage Notes This parameter is supported by the TCP/IP, TCP/IP with TLS, and SDP protocols. Put this parameter under the Setting this parameter in the connect descriptor for a client overrides the
RECV_BUF_SIZE parameter at the client-side Note: Additional protocols might support this parameter on certain operating systems. Refer to the operating system-specific documentation for additional information about additional protocols. Default The default value for this parameter is specific to the operating system. The default for the Linux 2.6 operating system is 87380 bytes. Example
6.8.5 SDUPurpose To instruct Oracle Net to optimize the transfer rate of data packets being sent across the network with a specified session data unit (SDU) size. Usage Notes Put this
parameter under the Setting this parameter in the connect descriptor for a client overrides the Default 8192 bytes (8 KB) Values 512 to 2097152 bytes. Example
6.8.6 SEND_BUF_SIZEUse the Purpose To specify, in bytes, the buffer space for send operations of sessions. Usage Notes This parameter is supported by the TCP/IP, TCP/IP with TLS, and SDP protocols. Put this parameter under the Setting this parameter in the connect descriptor for a client overrides the
SEND_BUF_SIZE parameter at the client-side Note: Additional protocols might support this parameter on certain operating systems. Refer to the operating system-specific documentation for information about additional protocols. Default The default value for this parameter is operating system specific. The default for the Linux 2.6 operating system is 16 KB. Example
6.8.7 SOURCE_ROUTEPurpose To enable routing through multiple protocol addresses. Usage Notes When you set this parameter to To use Oracle Connection Manager, an initial connection from the client to Oracle Connection Manager is required, and a second connection from Oracle Connection Manager to the listener is required. Put this parameter under either the Default off Values
Example net_service_name=
(DESCRIPTION=
(SOURCE_ROUTE=on)
(ADDRESS=(PROTOCOL=tcp)(HOST=cman-pc)(PORT=1630))
(ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) 6.8.8 TYPE_OF_SERVICEPurpose To specify the type of service to use for an Oracle Rdb database. Usage Notes This parameter should only be used if the application supports both an Oracle Rdb and Oracle database service, and you want the application to load balance between the two. Put this parameter under the
Example net_service_name=
(DESCRIPTION_LIST=
(DESCRIPTION=
(ADDRESS= 6.9 Connection Data SectionLearn how to configure network connections with protocol addresses. A network object is identified by a protocol address. When a connection is made, the client and the receiver of the request (listener or Oracle Connection Manager) are configured with identical protocol addresses. The client uses this address to send the connection request to a particular network object location, and the recipient "listens" for requests on this address, and grants a connection based on its address information matching the client information.
6.9.1 COLOCATION_TAGPurpose To direct the listener to route all connections with the same Usage Notes Use this parameter with the The parameter value must be an alphanumeric string. Example
Note: Under certain conditions, such as, when maximum load of an instance is reached or when new instances are added or deleted for a service, the colocation of client connections that have the same 6.9.2 CONNECT_DATA6.9.3 FAILOVER_MODEPurpose To instruct Oracle Net to fail over to a different listener if the first listener fails during run time. Usage Notes Depending upon the configuration, the session or any This type of failover is called Transparent Application Failover (TAF) and should not be confused with the connect-time failover FAILOVER parameter. Put this parameter under the Additional Parameters
Note: If a callback function is registered, then 6.9.4 GLOBAL_NAMEPurpose To identify the Oracle Rdb database. Usage Notes Put this parameter under the Example
6.9.5 HSPurpose To direct Oracle Net to connect to a non-Oracle system through Heterogeneous Services. Usage Notes Put this parameter under the Default None Values ok Example
6.9.6 INSTANCE_NAMEPurpose To identify the database instance to access. Usage Notes Set the value to the value specified by the Put this parameter under the Example
6.9.7 KERBEROS5_PRINCIPALUse this parameter to specify Kerberos principals. Purpose When you configure Kerberos authentication for an Oracle Database client, you can specify multiple Kerberos principals with a single Oracle Database client. This is an optional parameter. When specified, it is used to verify if the principal name in the credential cache matches the parameter value. Usage Notes Use this parameter with the Example For a
user
Note: The connection fails if the principal in the Similarly, for a user
6.9.8 RDB_DATABASEPurpose To specify the file name of an Oracle Rdb database. Usage Notes Put this parameter under the Example
6.9.9 SHARDING_KEYUse this parameter to route the database connection request to an appropriate shard. Put this parameter under
the Purpose To specify the value of sharding key. Based on the value specified during a database connection request, the request is directly routed to an appropriate shard. Usage Notes Use the
Use the Values The fields for base64-encoded values (
In the above syntax:
Example 6-8 In the following sample connect string, the
Example 6-9 In the following sample connect string, the
6.9.10 SUPER_SHARDING_KEYUse this
parameter in the case of composite sharding to route the database request to a collection of shards (shardspace). Put this parameter under the Purpose To specify shardspace key for a collection of shards. A shardspace is set of shards that store data that corresponds to a range or list of key values. Based on the value specified during a database connection request, the request is directly routed to an appropriate shardspace. Usage Notes Use the Use the
Values The fields for base64-encoded values (
For details on each of the base64-encoded header fields, see SHARDING_KEY. Example 6-10 In the following sample connect string, the
Example 6-11 In the following sample connect string, the
6.9.11 SERVERPurpose To direct the listener to connect the client to a specific type of service handler. Usage Notes Put this parameter under the Values
Note:
Example
6.9.12 SERVICE_NAMEPurpose To identify the Oracle Database database service to access. Usage Notes Set the value to a value specified by the Put this parameter under the Example
6.10 Security SectionThe security section of the
6.10.1 IGNORE_ANO_ENCRYPTION_FOR_TCPSThe Purpose To specify if the Usage Notes If your requirements are that Example 6-12 Example
6.10.2 OCI_COMPARTMENTUse the Purpose To define the scope of your database token request. This value instructs the database client to initiate a token request to databases within the specified compartment only. Usage Notes You can use the With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal. The If you do not set both Use this parameter under the Value OCID for the IAM compartment to allow access for the database token. You can get the OCID value for your compartment from the Compartments information page in the OCI console. The compartment OCID uses this syntax:
For details on the syntax options, see Oracle Cloud IDs (OCIDs). Examples In the
In the
6.10.3 OCI_DATABASEUse the Purpose To define the scope of your database token request. The database OCID value instructs the database client to initiate a token request to the specified database within your compartment. Usage Notes This parameter is optional. You can use the With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal. The Use this parameter under the Value OCID of the database that you want to access for the client connection. You can get the OCID value for your database from the Database details page in the OCI console. The database OCID uses this syntax:
For details on the syntax options, see Oracle Cloud IDs (OCIDs). Examples In the
In the
6.10.4 OCI_IAM_URLUse the Purpose To specify the IAM URL for your REST API requests. The database client connects to this URL to retrieve the database token from IAM. Usage Notes You set the With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal. You can also set the optional Use this parameter under the Value OCI IAM endpoint URL that the database client must connect with to get the database token. This URL is specific to your region and uses this syntax:
You can derive this value by replacing <authentication_regional_endpoint> with the API endpoint URL for your region. To obtain the appropriate API endpoint URL, see Identity and Access Management Data Plane API. For example, if you want to use the Phoenix URL (
Examples In the
In the
In these examples, the optional 6.10.5 OCI_TENANCYUse the Purpose To specify the OCID of the user’s tenancy (root compartment). Usage Notes You set the With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal. You can also set the optional Use this parameter under the Value OCID of the user’s tenancy. You can get the OCID value for your tenancy from the Tenancy information page in the OCI console. The tenancy OCID uses this syntax:
For details on the syntax options, see Oracle Cloud IDs (OCIDs). Examples In the
In the
In these examples, the optional 6.10.6 PASSWORD_AUTHUse the Purpose To configure either IAM database password verifier authentication or IAM token-based authentication using the IAM user name and IAM database password for the access. For password verifier authentication, the database server retrieves an IAM database password
verifier from IAM. For token-based authentication, the database client requests a database token ( Usage Notes
Note: You can also use other IAM user credentials (such as API-key, security token, resource principal, service principal, instance principal, or delegation token) to get the Unlike the IAM database password that can only be used by the database client to retrieve the token, these credentials require an application or tool to retrieve the token. See TOKEN_AUTH. Default
Values and Examples
6.10.7 SECURITYUse the Purpose To change the security properties of a connection. Put this parameter under the Example
6.10.8 SSL_SERVER_CERT_DNUse the Purpose To specify the distinguished name (DN) of the database server. Usage Notes The server DN must be known by the client ahead of time. Otherwise, the client cannot specify the server's DN in Use this parameter with the Example
6.10.9 TOKEN_AUTHUse the Purpose Token-based access enforces strong authentication, which enables a more secure access to the database. IAM users can connect to OCI Database as a Service (DBaaS) databases, and Azure AD users can connect to Oracle Databases (cloud or on-premises). Use this parameter under the Usage Notes for IAM
Note: You can also use another IAM credential, IAM database password, to request the Unlike the API-key, security token, resource principal, service principal, instance principal, and delegation token that require an application or tool to get a token, the IAM database password can only be used by the database client to retrieve the token. See PASSWORD_AUTH. Table 6-1 Values and Examples for IAM
Usage Notes for Azure AD
Table 6-2 Values and Examples for Azure AD
Related Topics
6.10.10 TOKEN_LOCATIONUse the Purpose To specify the directory location where token file is stored for token-based authentication. For Azure AD, you can also specify the token file name. The database client gets the token from this location and sends it to the database server. Use this parameter along with the Usage Notes for IAM The When an IAM user initiates a connection using Table 6-3 Values and Examples for IAM
Usage Notes for Azure AD The If your token file is named
When an Azure AD user initiates a connection using Table 6-4 Values and Examples for Azure AD
Related Topics
6.11 Timeout ParametersThe timeout section of the The following parameters can be set at the
6.11.1 CONNECT_TIMEOUTPurpose To specify the timeout duration in Usage Notes Put this parameter under the The timeout interval specified by The timeout interval is applicable for each The Example
6.11.2 RETRY_COUNTPurpose To specify the number of times an Usage Notes Put this parameter under the When a Example
6.11.3 RETRY_DELAYPurpose To specify the delay in seconds between subsequent retries for a connection. This parameter works in conjunction with Usage Notes Put this parameter under the When a Example
6.11.4 TRANSPORT_CONNECT_TIMEOUTPurpose To specify the transport connect timeout duration in Usage Notes This parameter is put under the The The timeout interval is applicable for each Example net_service_name = (DESCRIPTION= (TRANSPORT_CONNECT_TIMEOUT=10 ms) (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))) (CONNECT_DATA= (SERVICE_NAME=sales.us.example.com))) 6.11.5 RECV_TIMEOUTUse the Purpose To specify the time, in You can specify the time in hours, minutes, seconds, or milliseconds by using the Usage Notes This parameter is put under the Setting this parameter for clients ensures that receive operations are not left in a wait state indefinitely or for a long period due to server host being down, server busy state, or network connectivity issues. If a client does not receive response data in
the time specified, then the client logs Recommended Value Any number greater than the minimum value of Example RECV_TIMEOUT=10ms or
6.12 Compression ParametersThe compression section of the
6.12.1 COMPRESSIONThe Purpose To enable or disable data compression. Usage Notes Put this parameter under the Setting this parameter in the connect descriptor for a client overrides the Values
Example
6.12.2 COMPRESSION_LEVELSThe Purpose To specify the compression level. Usage Notes The compression levels are used at the time of negotiation to verify which levels are used at both ends, and select one level. Put this parameter under the This parameter is used with the Values
Example |