Oracle® Database Net Services Reference 10g Release 2 (10.2) Part Number B14213-01 |
|
|
View PDF |
This chapter provides a complete listing of the tnsnames.ora
file configuration parameters.
This chapter contains these topics:
This tnsnames.ora
file is a configuration file that contains net service names mapped to connect descriptors for the local naming method, or net service names mapped to listener protocol addresses.
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, tnsnames.ora
is located in the $ORACLE_HOME/network/admin
directory on UNIX operating systems and in the ORACLE_HOME
\network\admin
directory on Windows operating systems. tnsnames.ora
can also be stored the following locations:
The directory specified by the TNS_ADMIN
environment variable or registry value
On UNIX operating systems, the global configuration directory. For example, on the Solaris Operating System, this directory is /var/opt/oracle
.
See Also:
Oracle operating system-specific documentationThe basic syntax for a tnsnames.ora
file is shown in . DESCRIPTION
contains the connect descriptor, ADDRESS
contains the protocol address, and CONNECT_DATA
contains the database service identification information.
A tnsnames.ora
file can contain net service names with one or more connect descriptors. Each connect descriptor can contain one or more protocol addresses. Example 6-2 shows two connect descriptors with multiple addresses. DESCRIPTION_LIST
defines a list of connect descriptors.
Note:
Oracle Net Manager does not support the creation of multiple connect descriptors for a net service name.Example 6-2 Net Service Name with Multiple Connect Descriptors in tnsnames.ora
net_service_name= (DESCRIPTION_LIST= (DESCRIPTION= (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information)) (CONNECT_DATA= (SERVICE_NAME=service_name))) (DESCRIPTION= (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information)) (CONNECT_DATA= (SERVICE_NAME=service_name))))
The tnsnames.ora
file also supports connect descriptors with multiple lists of addresses, each with its own characteristics. In , two address lists are presented. The first address list features client load balancing and no connect-time failover, affecting only those protocol adresses within the ADDRESS_LIST
. The second protocol address list features connect-time failover and no client load loading balancing, affecting only those protocol addresses within the ADDRESS_LIST
. The client first tries either the first or second protocol address at random, then tries protocol addresses three and four sequentially.
Note:
Oracle Net Manager supports only the creation of one protocol address list for a connect descriptor.Example 6-3 Multiple Address Lists in tnsnames.ora
net_service_name= (DESCRIPTION= (ADDRESS_LIST= (LOAD_BALANCE=on) (FAILOVER=off) (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information))) (ADDRESS_LIST= (LOAD_BALANCE=off) (FAILOVER=on) (ADDRESS=(protocol_address_information)) (ADDRESS=(protocol_address_information))) (CONNECT_DATA= (SERVICE_NAME=service_name)))
Note:
Protocol address lists do not have to be embedded in anADDRESS_LIST
if there is only one list, as was the case prior to release 8.1.When a connect descriptor in a tnsnames.ora
file contains at least two protocol addresses for Oracle Connection Manager, parameters for connect-time failover and load balancing can be included in the file.
illustrates failover of multiple Oracle Connection Manager protocol addresses.
Example 6-4 Multiple Oracle Connection Manager Addresses in tnsnames.ora
sample1= (DESCRIPTION= (SOURCE_ROUTE=yes) (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630)) # hop 1 (ADDRESS_LIST= (FAILOVER=on) (LOAD_BALANCE=off) # hop 2 (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630))) (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1521)) # hop 3 (CONNECT_DATA=(SERVICE_NAME=Sales.us.acme.com)))
In :
The client is instructed to connect to an protocol address of the first Oracle Connection Manager, as indicated by:
(ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))
The first Oracle Connection Manager is then instructed to connect to the first protocol address of another Oracle Connection Manager. If the first protocol address fails, then it tries the second protocol address. This sequence is specified with the following configuration:
(ADDRESS_LIST= (FAILOVER=ON) (LOAD_BALANCE=off) (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630))
The Oracle Connection Manager then connects to the database service using the following protocol address:
(ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1521))
illustrates client load balancing among two Oracle Connection Managers and two protocol addresses:
Example 6-5 Client Load Balancing in tnsnames.ora
sample2= (DESCRIPTION= (LOAD_BALANCE=on) (FAILOVER=on) (ADDRESS_LIST= (SOURCE_ROUTE=yes) (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=1521))) (ADDRESS_LIST= (SOURCE_ROUTE=yes) (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=1521))) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))
In :
The client is instructed to pick an ADDRESS_LIST
at random and to failover to the other if the chosen ADDRESS_LIST
fails. This is indicated by the LOAD_BALANCE
and FAILOVER
parameters being set to on
.
When an ADDRESS_LIST
is chosen, the client first connects to the Oracle Connection Manager, using the Oracle Connection Manager protocol address that uses port 1630 indicated for the ADDRESS_LIST
.
The Oracle Connection Manager then connects to the database service, using the protocol address indicated for the ADDRESS_LIST
.
This section lists and describes the tnsnames.ora
file parameters that comprise connect descriptors. Configuration parameters fall into the following categories:
Each connect descriptor is contained within a DESCRIPTION
parameter. Multiple connect descriptors are characterized by the DESCRIPTION_LIST
parameter. These parameters are described next.
Purpose
Use the DESCRIPTION
parameter as a container for a connect descriptor.
Embed this parameter under the DESCRIPTION_LIST
parameter.
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))
Purpose
Use he DESCRIPTION_LIST
parameter defines a list of connect descriptors for a particular net service name.
Example
net_service_name= (DESCRIPTION_LIST= (DESCRIPTION= (ADDRESS=...) (CONNECT_DATA=(SERVICE_NAME=sales.acme.com))) (DESCRIPTION= (ADDRESS=...) (CONNECT_DATA=(SERVICE_NAME=sales2.us.acme.com))))
The protocol address section of the tnsnames.ora
file specifies the protocol addresses of the listener.
Purpose
Use the parameter ADDRESS
to define a single listener protocol address.
Embed this parameter under either the ADDRESS_LIST
parameter or the DESCRIPTION
parameter.
See Also:
Chapter 4 for descriptions of the correct parameters to use for each protocolExample
net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales-svr)(PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com))
Purpose
Use the parameter ADDRESS_LIST
to define a list of protocol addresses. If there is only address list, ADDRESS_LIST
is not necessary.
Embed this parameter under either the DESCRIPTION
parameter or the DESCRIPTION_LIST
parameter.
Example
net_service_name= (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))) (ADDRESS_LIST= (FAILOVER=on) (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))
For multiple addresses, the following parameters are available for usage:
Use the parameter FAILOVER
to enable or disable connect-time failover for multiple protocol addresses.
When you set the parameter to on
, yes
, or true
, Oracle Net, at connect time, fails over to a different address if the first protocol address fails. When you set the parameter to off
, no
, or false
, Oracle Net tries one protocol address.
Embed this parameter under either the DESCRIPTION_LIST
parameter, the DESCRIPTION
parameter, or the ADDRESS_LIST
parameter.
Important:
Do not set theGLOBAL_DBNAME
parameter in the SID_LIST_
listener_name
section of the listener.ora
. A statically configured global database name disables connect-time failover.Default
on
for DESCRIPTION_LIST
s, DESCRIPTION
s, and ADDRESS_LIST
s
Values
on | off | yes | no | true | false
Example
net_service_name= (DESCRIPTION= (FAILOVER=on) (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))
Use the parameter LOAD_BALANCE
to enable or disable client load balancing for multiple protocol addresses.
When you set the parameter to on
, yes
, or true
, Oracle Net progresses through the list of addresses in a random sequence, balancing the load on the various listener or Oracle Connection Manager protocol addresses. When you set the parameter to off
, no
, or false
, Oracle Net tries the protocol addresses sequentially until one succeeds.
Embed this parameter under either the DESCRIPTION_LIST
parameter, the DESCRIPTION
parameter, or the ADDRESS_LIST
parameter.
Default
on
for DESCRIPTION_LIST
s
Values
on | off | yes | no | true | false
Example
net_service_name= (DESCRIPTION= (LOAD_BALANCE=on) (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com))
Purpose
Use the parameter RECV_BUF_SIZE
to specify, in bytes, the buffer space for receive operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.
Note:
Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support this parameter.Embed this parameter under the DESCRIPTION
parameter or at the end of the protocol address.
Default
The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 32768 bytes.
Usage
Setting this parameter in the connect descriptor for a client overrides the RECV_BUF_SIZE parameter at the clientside sqlnet.ora
file.
See Also:
Oracle Database Net Services Administrator's Guide for information about configuring this parameterExample
net_service_name= (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521) (RECV_BUF_SIZE=11784)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521) (RECV_BUF_SIZE=11784)) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com))) net_service_name= (DESCRIPTION= (RECV_BUF_SIZE=11784) (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=hr1-server)(PORT=1521) (ADDRESS=(PROTOCOL=tcp)(HOST=hr2-server)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=hr.us.acme.com)))
Purpose
Use the parameter SDU
to instruct Oracle Net to optimize the transfer rate of data packets being sent across the network with the session data unit (SDU) size you specify.
Embed this parameter under the DESCRIPTION
parameter.
Default
2048 bytes (2KB)
Values
512 bytes to 32768 (32 KB)
Usage
Setting this parameter in the connect descriptor for a client overrides the DEFAULT_SDU_SIZE parameter at clientside sqlnet.ora
file.
See Also:
Oracle Database Net Services Administrator's Guide for complete SDU usage and configuration informationExample
net_service_name= (DESCRIPTION= (SDU=2085) (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521))) (CONNECT_DATA= (SERVER_NAME=sales.us.acme.com))
Purpose
Use the parameter SEND_BUF_SIZE
to specify, in bytes, the buffer space for send operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.
Note:
Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support this parameter.Embed this parameter under the DESCRIPTION
parameter or at the end of the protocol address.
Default
The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 8192 bytes.
Usage
Setting this parameter in the connect descriptor for a client overrides the SEND_BUF_SIZE parameter at the clientside sqlnet.ora
file.
See Also:
Oracle Database Net Services Administrator's Guide for information about configuring this parameterExample
net_service_name= (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521) (SEND_BUF_SIZE=11784)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521) (SEND_BUF_SIZE=11784)) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com))) net_service_name= (DESCRIPTION= (SEND_BUF_SIZE=11784) (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=hr1-server)(PORT=1521) (ADDRESS=(PROTOCOL=tcp)(HOST=hr2-server)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=hr.us.acme.com)))
Purpose
Use the parameter SOURCE_ROUTE
to enable routing through multiple protocol addresses.
When you set to on
or yes
, Oracle Net uses each address in order until the destination is reached.
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.
Embed this parameter under either the DESCRIPTION_LIST
parameter, the DESCRIPTION
parameter, or the ADDRESS_LIST
parameter.
See Also:
Oracle Database Net Services Administrator's Guide for complete configuration informationDefault
off
Values
yes | no | on | off
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.acme.com))
Purpose
Use the parameter TYPE_OF_SERVICE
parameter to specify the type of service to use for an Oracle Rdb database. 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.
Embed this parameter under the DESCRIPTION
parameter.
Example
net_service_name= (DESCRIPTION_LIST= (DESCRIPTION= (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=generic) (RDB_DATABASE=[.mf]mf_personal.rdb) (GLOBAL_NAME=alpha5)) (TYPE_OF_SERVICE=rdb_database)) (DESCRIPTION= (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com)) (TYPE_OF_SERVICE=oracle9_database)))
The connection data section of the tnsnames.or
a file specifies the name of the destination service.
Purpose
Use the parameter CONNECT_DATA
to define the service to which to connect.
Embed this parameter under the DESCRIPTION
parameter.
Usage Notes
CONNECT_DATA
permits the following subparameters:
Example
net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com)))
Purpose
Use the parameter FAILOVER_MODE
to instruct Oracle Net to fail over to a different listener if the first listener fails during runtime. Depending upon the configuration, session or any SELECT
statements which were in progress are automatically failed over.
This type of failover is called Transparent Application Failover (TAF) and should not be confused with the connect-time failover FAILOVER parameter.
Embed this parameter under the CONNECT_DATA
parameter.
See Also:
Oracle Database Net Services Administrator's Guide for complete configuration informationSubparameters
FAILOVER_MODE
supports the following subparameters:
BACKUP
: Specify the failover node by its net service name. A separate net service name must be created for the failover node.
TYPE
: Specify the type of failover. Three types of Oracle Net failover functionality are available by default to Oracle Call Interface (OCI) applications:
session
: Fails over the session; that is, if a user's connection is lost, a new session is automatically created for the user on the backup. This type of failover does not attempt to recover selects.
select
: Allows users with open cursors to continue fetching on them after failure. However, this mode involves overhead on the client side in normal select operations.
none
: This is the default, in which no failover functionality is used. This can also be explicitly specified to prevent failover from happening.
METHOD
: Specify how fast failover is to occur from the primary node to the backup node:
basic
: Establishes connections at failover time. This option requires almost no work on the backup database server until failover time.
preconnect
: Pre-establishes connections. This provides faster failover but requires that the backup instance be able to support all connections from every supported instance.
RETRIES
: Specify the number of times to attempt to connect after a failover. If DELAY
is specified, RETRIES
defaults to five retry attempts.
DELAY
: Specify the amount of time in seconds to wait between connect attempts. If RETRIES
is specified, DELAY
defaults to one second.
Note:
If a callback function is registered, thenRETRIES
and DELAY
subparameters are ignored.Example
See Also:
Oracle Database Net Services Administrator's Guide for implementation examplesPurpose
Use the parameter GLOBAL_NAME
to identify the Oracle Rdb database.
Embed this parameter under the CONNECT_DATA
parameter.
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=generic) (RDB_DATABASE=[.mf]mf_personal.rdb) (GLOBAL_NAME=alpha5)))
Purpose
Use the parameter HS
to instruct Oracle Net to connect to a non-Oracle system through Heterogeneous Services.
Embed this parameter under the CONNECT_DATA
parameter.
See Also:
Oracle Database Net Services Administrator's Guide for complete configuration informationDefault
None
Values
ok
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SID=sales6) (HS=ok)))
Purpose
Use the parameter INSTANCE_NAME
to identify the database instance to access. Set the value to the value specified by the INSTANCE_NAME
parameter in the initialization parameter file.
Embed this parameter under the CONNECT_DATA
parameter.
See Also:
Oracle Database Net Services Administrator's Guide for information about the use ofINSTANCE_NAME
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com) (INSTANCE_NAME=sales1)))
Purpose
Use the parameter RDB_DATABASE
parameter to specify the file name of an Oracle Rdb database.
Embed this parameter under the CONNECT_DATA
parameter.
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com) (RDB_DATABASE= [.mf]mf_personal.rdb)))
Purpose
Use the parameter SERVER
to instruct the listener to connect the client to a specific type of service handler.
Embed this parameter under the CONNECT_DATA
parameter.
Values
dedicated
to specify that client requests be served by dedicated server
shared
to specify that client request be served by shared server
Note:
Shared server must be configured in the database initialization file in order for the client to connect to the database with a shared server process. See the Oracle Database Net Services Administrator's Guide for configuration information.Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVER_NAME=sales.us.acme.com) (SERVER=dedicated)))
Purpose
Use the parameter SERVICE_NAME
to identify the Oracle9i or Oracle8 database service to access. Set the value to a value specified by the SERVICE_NAMES
parameter in the initialization parameter file.
Embed this parameter under the CONNECT_DATA
parameter.
See Also:
Oracle Database Net Services Administrator's Guide for information about the use of theSERVICE_NAME
parameterExample
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com)))
Purpose
Use the parameter SID
to identify the Oracle8 database instance by its Oracle System Identifier (SID). If the database is Oracle9i or Oracle8, use the SERVICE_NAME parameter rather than the SID
parameter.
Embed this parameter under the CONNECT_DATA
parameter.
Example
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SID=sales)))
The security section of the tnsnames.or
a file specifies security-related parameters for use with Oracle Advanced Security features.
Purpose
Use the parameter SECURITY
to enable secure connections.
Embed this parameter under the DESCRIPTION
parameter.
Usage Notes
SECURITY
permits the SSL_SERVER_CERT_DN subparameter.
Example
net_service_name=
(DESCRIPTION=
(ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))
(CONNECT_DATA=
(SERVICE_NAME=sales.us.acme.com))
(SECURITY=
(SSL_SERVER_CERT_DN="cn=sales,cn=OracleContext,dc=us,dc=acme,dc=com")))
Purpose
Use the parameter SSL_SERVER_CERT_DN
to specify the distinguished name (DN) of the database server. The client uses this information to obtain the list of DNs it expects for each of the servers, enforcing the database server DN to match its service name.
Usage Notes
Use this parameter in conjunction with the sqlnet.ora
parameter SSL_SERVER_DN_MATCH to enable server DN matching.
net_service_name= (DESCRIPTION= (ADDRESS=...) (ADDRESS=...) (CONNECT_DATA= (SERVICE_NAME=finance.us.acme.com)) (SECURITY= (SSL_SERVER_CERT_DN="cn=finance,cn=OracleContext,dc=us,dc=acme,dc=com")))