3
Oracle Names Control Utility

This chapter describes the commands and associated syntax of the Oracle Names Control utility.

This chapter contains these topics:

Oracle Names Control Utility Overview

The Oracle Names Control utility enables you to administer Oracle Names servers. You can use its commands to perform basic management functions on one or more Oracle Names servers. Additionally, you can view and change parameter settings.

The basic syntax of Oracle Names Control utility administrative commands is as follows:

namesctl command [onames_server]

where onames_server is the name of the Oracle Names server to be administered.

You can also issue Oracle Names Control utility commands at the NAMESCTL> program prompt. To obtain the prompt, enter namesctl with no arguments at the operating system command line. When you run namesctl, the program is started. You can then enter the necessary commands from the program prompt. The basic syntax of issuing commands from NAMESCTL> program prompt is as follows:

namesctl
NAMESCTL> command [onames_server]

When you start the Oracle Names Control utility, it starts a session with an Oracle Names server. The session is started with the first Oracle Names server listed in the discovery file (.sdns.ora on UNIX operating systems and sdns.ora on Windows operating systems) or the sqlnet.ora file (by the NAMES.PREFERRED_SERVERS parameter). The SHOW SERVER commands display the Oracle Names server that the Oracle Names Control utility is currently managing. If you want to start a session with another Oracle Names server, then use the SET SERVER command.

Note:

The START command starts a session with the Oracle Names server that is started, even if the Oracle Names Control utility had a session with another Oracle Names server.

Note:

You can combine commands in a standard text file, and then run them as a sequence of commands. To execute in batch mode, use the format:

namesctl @file_name

You can use either REM or # to identify comments in the batch script; all other lines are considered commands. Any commands that would typically require confirmation do not require confirmation during batch execution.

The Oracle Names Control utility supports several types of administrative commands:

Operational commands, such as START, STOP, and RESTART
Modifier commands, such as SET TRACE_LEVEL
Informational commands, such as STATUS, SHOW LOG_FILE_NAME, and PING
Command utility operational commands, such as EXIT, QUIT, and HELP

The Oracle Names Control utility also provides data operations command, such as QUERY and REGISTER.

SET and SHOW Commands of the Oracle Names Control Utility

You can use the SET command to change some parameter values for an Oracle Names server or the Oracle Names Control utility environment. Parameter values remain in effect until the Oracle Names server is shut down. If you want these settings to persist, use the SAVE_CONFIG, SET SAVE_CONFIG_ON_STOP, or SET SAVE_CONFIG_INTERVAL commands to save changes to the names.ora.

You can use the SHOW command to display the current value of a configuration setting.

Distributed Operations

The Oracle Names Control utility can perform operations on a local or a remote Oracle Names server. This is useful when a single administrator is managing all of the Oracle Names servers in a region, or wants to check the availability of a specific Oracle Names server.

To set up a computer to remotely administer an Oracle Names server, ensure that the Oracle Names Control utility (namesctl) executable is installed.

All commands except START can be issued when an Oracle Names server is administered remotely. The Oracle Names Control utility can only start the Oracle Names server on the same computer from where the utility is running.

When issuing commands, specify the name of the Oracle Names server as an argument. For example:

NAMESCTL> SHOW SYSTEM_QUERIES dolphin.us.acme.com

If the Oracle Names Control utility cannot locate the Oracle Names server, then a name lookup error appears:

NNL-00406: name "dolphin.us.acme.com" does not exist

If you know the protocol address of the particular Oracle Names server, then enter it in place of the name of the Oracle Names server. For example:

 NAMESCTL> SHOW SYSTEM_QUERIES 
(ADDRESS=(PROTOCOL=tcp)(HOST=dolphin.us.acme.com)(PORT=1575))

When the name omitted, the Oracle Names server that the Oracle Names Control utility has a session with is assumed. If a session cannot be established with any Oracle Names server, then the following error appears:

NNL-00005: no server has been set. Use the "SET SERVER" command first

Use the SET SERVER command to establish a session with an Oracle Name server.

Once remote access is established, all commands except START can be issued.

See Also:

"Oracle Names Control Utility Overview" for further information about session establishment

Oracle Names Server Security

If the NAMES.PASSWORD parameter is set in the names.ora, then the Oracle Names Control utility requires a SET PASSWORD command for any sensitive operations, such as stopping an Oracle Names server.

If the NAMESCTL.SERVER_PASSWORD parameter is set in the sqlnet.ora file on the node running the Oracle Names Control utility, you are prompted to use the SET PASSWORD command each time a secure operation is performed.

If you are concerned with the security implications of explicitly putting an Oracle Names server password in the client sqlnet.ora file, you can omit the NAMESCTL.SERVER_PASSWORD parameter and always use the command:

NAMESCTL> SET PASSWORD

When passed over the network, the password is encrypted, regardless of how it was set in the names.ora file. However, if the NAMESCTL.INTERNAL_ENCRYPT_PASSWORD parameter is set to false in the sqlnet.ora file, then the password is not encrypted.

Confirmation Mode in the Oracle Names Control Utility

Some of the Oracle Names Control utility commands require confirmation before they are executed. When you issue the command, you are prompted:

confirm:[yes or no]

Enter yes to execute the command; enter no to cancel the command.

You can turn confirmation mode off by setting the parameter NAMESCTL.NOCONFIRM to true in the sqlnet.ora file.

Oracle Names Control Utility Commands

This section lists and describes the Oracle Names Control utility commands.

DELEGATE_DOMAIN

Purpose

Use the command DELEGATE_DOMAIN to define a domain as the start of a subregion for the current administrative region.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl DELEGATE_DOMAIN {domain}{onames_server}{(ADDRESS=...)}

From the Oracle Names Control utility:

NAMESCTL> DELEGATE_DOMAIN {domain}{onames_server}{(ADDRESS=...)}

Arguments

{domain}: Specify the domain name.

{onames_server}: Specify the Oracle Names server name.

{(ADDRESS=...)}: Specify the Oracle Names server protocol address.

See Also:

Chapter 5, "Protocol Address Configuration" for further information about defining protocol addresses

Usage Notes

This command provides a dynamic way to subdivide the namespace.

Unless a domain is delegated from a region, the Oracle Names servers in that region assume authority over all subdomains. In order to delegate a domain, you must first create a new region.

Once a domain is delegated, the Oracle Names servers in the current administrative region forward subsequent operations to the subregion where the domain is administered by Oracle Names servers.

Examples

NAMESCTL> DELEGATE_DOMAIN webwidgets.acme.com ns1.webwidgets.acme.com 
(ADDRESS=(PROTOCOL=tcp)(HOST=fred.webwidgets.acme.com)(PORT=1575))

DOMAIN_HINT

Purpose

Use the command DOMAIN_HINT to specify domain hints for requests for data from remote regions. A domain hint contains the name of a remote domain and at least one address of an Oracle Names server in that domain. A hint enables the Oracle Names server to forward the request to a specific address, reducing network traffic.

Without a domain hint, an Oracle Names server forwards a request to whatever remote Oracle Names servers it knows, which then forwards the request to the root Oracle Names server in its region. The root Oracle Names server forwards the request to the Oracle Names server which has information on the domain that the request refers to.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl DOMAIN_HINT {domain}{onames_server}{(ADDRESS=...)}

From the Oracle Names Control utility:

NAMESCTL> DOMAIN_HINT {domain}{onames_server}{(ADDRESS=...)}

Arguments

{domain}: Specify the domain name.

{onames_server}: Specify the Oracle Names server name.

{(ADDRESS=...)}: Specify the Oracle Names server protocol address.

See Also:

Chapter 5, "Protocol Address Configuration" for further information about defining protocol addresses

Usage Notes

Any region that is not the root region will need at least the root region defined using this command in order to find objects in any other region. You can provide additional hints as optimizations to provide local Oracle Names servers with direct access to certain other regions.

Examples

NAMESCTL> DOMAIN_HINT ACME.COM ns0.acme.com (ADDRESS=(PROTOCOL=tcp) 
(HOST=top.acme.com)(PORT=1575))

DUMP_ALIAS

Purpose

Use the command DUMP_ALIAS to query all the alias data in a domain or domain subtree and export the data to a LDAP-compliant directory service or into an LDAP Data Interchange Format (LDIF) file, which can later be loaded into a directory.

Notes:

Net service aliases are not supported using Microsoft Active Directory.
This command does not verify that the object the alias is referencing exists in the directory. If an alias is exported and the object is referencing is not exported, then the DUMP_ALIAS command exports the alias without verifying that the referenced database service or net service name exists.
The command should use the same destination as applied with the DUMP_LDAP command to the object the alias is referencing. If an alias and the object it is referencing are exported with different destinations, then the net service alias will not contain the correct name for the object it is referencing. This can occur in a case of tree rearrangement. See Oracle9i Net Services Administrator's Guide for further information.

Prerequisites

The directory must already have the Oracle schema and one or more Oracle Contexts.

Password Required If One Has Been Set

A password for the directory may be required.

Syntax

Exporting Data to an LDIF File

NAMESCTL> DUMP_ALIAS [source] [destination] [options] {-f [filename]}

Exporting Data To a Directory

NAMESCTL> DUMP_ALIAS [source] [destination] [options] {-h host} {-p port} {-D 
user_dn} {-w password}

Arguments

[source]: Specify the source Oracle Names domain and, optionally, the -R argument:

{domain}: Specify the domain name for aliases to be exported. The default domain is the root. The operation is forwarded to an Oracle Names server that is authoritative for that domain if the Oracle Names server which the client contacts is not authoritative.

[-R]: Specify to recursively descend the Oracle Names tree structure. Without -R, this command looks only at objects in the specified domain.

[destination]: Specify the distinguished name (DN) in the directory information tree (DIT) where to export net service aliases. A DN can be specified in one of following ways:

A DN where all exported aliases will be located

For example, (dn:dc=acme,dc=com) specifies to export all aliases to cn=OracleContext under dc=acme,dc=com. By default, cn=OracleContext is automatically inserted.
A template to model the DIT structure where objects will be located

You create a template by specifying attributes for mapping subdomains to the corresponding attribute/value pairs in a DN. A destination of (dn:o,ou,dc), for example, maps to a DIT structure that contains an organization (o), organization unit (ou), and a domain component (dc).

When you use -R in the source argument, the domain in the source maps to the segment of the destination argument that contains the fully-specified attribute/value pairs, and subdomains of the source domain map to nodes specified in the destination argument by attributes without values. For example, if Oracle Names contains a root domain of acme.com and delegated domains of sales.acme.com and dev.acme.com, you can use a template of (dn:ou,o=acme,c=us) to create a DIT with a common structure of o=acme,c=us and unique subtrees of ou=sales and ou=dev. Using the -R argument exports data in one of two ways:
- If the destination is specified with a DN, then the DUMP_ALIAS command recursively descends the Oracle Names tree structure and exports all aliases in that structure to the destination node in the DIT. All the aliases in all the subdomains map to a single DIT node.
  
  Continuing with an example of an Oracle Names root domain of acme.com and delegated domains of sales.acme.com and dev.acme.com, issuing DUMP_ALIAS acme.com (dn:dc=acme,dc=com) -R
  exports all net services in acme.com, sales.acme.com, and dev.acme.com to dc=OracleContext,dc=acme,dc=com.
- If the destination is specified with a template, then the DUMP_ALIAS command recursively descends the Oracle Names tree structure and exports the aliases in the source domain and subdomains according to the template.
  
  Issuing DUMP_ALIAS acme.com (dn:ou,dc=acme,dc=com) -R exports aliases in acme.com to dc=OracleContext,dc=acme,dc=com, aliases in sales.acme.com to dc=OracleContext,ou=sales,dc=acme,dc=com, and aliases in dev.acme.com to dc=OracleContext,ou=dev,dc=acme,dc=com.

[options]: Arguments that specify how the export of the aliases is to occur:

-c: Specify that the export should continue on error.

-n: Specify to not perform an actual export. This argument enables you to perform a test run. The results display to the screen.

-m: Specify that existing entries in the DIT are to be modified.

-x: Specify to not include cn=OracleContext in each object's DN.

[-f filename]: Specify that the exported data dumped into an LDIF file, which can later be loaded into a directory. The default file name is onames.ldif. To use onames.ldif as the default name, specify -f as the last argument.

These arguments specify the location of the directory server:

[-h host]: Specify the host name of the directory server.

[-p port]: Specify the port number the directory is configured to listen on. The default TCP/IP port number is 389.

These arguments specify the authentication credentials of the directory server:

[-D user_dn]: Specify a directory administrator that has been given add and modify privileges. For example, cn=Mary is the DN for an administrator named Mary.

[-w password]: Specify the password for the directory administrator.

Usage Notes

Examples

Exporting Net Service Aliases to a LDIF File

NAMESCTL> DUMP_ALIAS acme.com (dn:dc=sales,dc=com) -R -f test.ldif

Exporting Net Service Aliases Directly Into a Directory

NAMESCTL> DUMP_ALIAS acme.com (dn:dc=sales,dc=com) -R -h ldap-server -p 
389 -D cn=orcladmin -w welcome

DUMP_LDAP

Purpose

Use the command DUMP_LDAP to query all the addresses of database objects in a domain or region and export the data to a LDAP-compliant directory service or into an LDIF file, which can later be loaded into a directory.

Note:

Because database objects are exported as net service names, the username and password credentials for a global database link or link qualifier is not exported with the address information. In the same way you used global database links in Oracle Names, you can use a net service name from a directory to access an object in a database. However, the net service name will behave as a connected user database link.

See Also:

Oracle9i Net Services Administrator's Guide for further information about using global database links
Oracle9i Database Administrator's Guide for information about the supported types of database link users
Oracle Advanced Security Administrator's Guide for information about configuring database links in a directory

Prerequisites

The directory must already have an Oracle schema and one or more Oracle Contexts.

Password Required If One Has Been Set

A password for the directory may be required.

Syntax

Exporting Data to an LDIF File

NAMESCTL> DUMP_LDAP [source] [destination] [options] {-f [filename]}

Exporting Data To a Directory

NAMESCTL> DUMP_LDAP [source] [destination] [options] {-h host} {-p port} {-D 
user_dn} {-w password}

Arguments

[source]: Specify the source Oracle Names domain and, optionally, the -R argument:

{domain}: Specify the domain name for objects to be exported. The default domain is the root. The operation is forwarded to an Oracle Names server that is authoritative for that domain if the Oracle Names server which the client contacts is not authoritative.

[-R]: Specify to recursively descend the Oracle Names tree structure. Without -R, this command looks only at objects in the specified domain.

[destination]: Specify the DN in the DIT where to export objects. A DN can be specified in one of following ways:

A DN where all exported aliases will be located

For example, (dn:dc=acme,dc=com) specifies to export objects to cn=OracleContext under dc=acme,dc=com. By default, cn=OracleContext is automatically inserted.
A template to model the DIT structure where objects will be located

You create a template by specifying attributes for mapping subdomains to the corresponding attribute/value pairs in a DN. A destination of (dn:o,ou,dc), for example, maps to a DIT structure that contains an organization (o), organization unit (ou), and a domain component (dc).

When you use -R in the source argument, the domain in the source maps to the segment of the destination argument that contains the fully-specified attribute/value pairs, and subdomains of the source domain map to nodes specified in the destination argument by attributes without values. For example, if Oracle Names contains a root domain of acme.com and delegated domains of sales.acme.com and dev.acme.com, you can use a template of (dn:ou,o=acme,c=us) to create a DIT with a common structure of o=acme,c=us and unique subtrees of ou=sales and ou=dev. Using the -R argument exports data in one of two ways:
- If the destination is specified with a DN, then the DUMP_ALIAS command recursively descends the Oracle Names tree structure and exports all net service names and database services in that structure to the destination node in the DIT. All the objects in all the subdomains map to a single DIT node.
  
  Continuing with the example of an Oracle Names root domain of acme.com and delegated domains of sales.acme.com and dev.acme.com, issuing
  DUMP_LDAP acme.com (dn:dc=acme,dc=com) -R
  exports all net service names and database services in acme.com, sales.acme.com, and dev.acme.com to dc=OracleContext,dc=acme,dc=com.
- If the destination is specified with a template, then the DUMP_ALIAS command recursively descends the Oracle Names tree structure and exports the net service names and database services in the source domain and subdomains according to the template.
  
  Issuing DUMP_LDAP acme.com (dn:ou,dc=acme,dc=com) -R
  exports objects in acme.com to dc=OracleContext,dc=acme,dc=com, objects in sales.acme.com to dc=OracleContext,ou=sales,dc=acme,dc=com, and objects in dev.acme.com to dc=OracleContext,ou=dev,dc=acme,dc=com.

[options]: Arguments that specify how the export of data is to occur:

-c: Specify that the export should continue on error.

-n: Specify to not perform an actual export. This argument enables you to perform a test run. The results display to the screen.

-m: Specify that existing entries in the DIT are to be modified.

-x: Specify to not include cn=OracleContext in each object's DN.

[-f filename]: Specify that the exported data be dumped into an LDIF file, which can later be loaded into a directory. The default file name is onames.ldif. To use onames.ldif as the default name, specify -f as the last argument.

These arguments specify the location of the directory server:

[-h host]: Specify the host name of the directory server.

[-p port]: Specify the port number the directory is configured to listen on. The default TCP/IP port number is 389.

These arguments specify the authentication credentials of the directory server:

[-D user_dn]: Specify a directory administrator that has been given add and modify privileges. For example, cn=mary is the DN for an administrator named Mary.

[-w password]: Specify the password for the directory administrator.

Usage Notes

Examples

Exporting Data to an LDIF File

NAMESCTL> DUMP_LDAP sj.us.sczi.com (dn:ou=sj,dc=us,dc=sczi,dc=com) -R -f 
test.ldif

Exporting Data Directly Into a Directory

NAMESCTL> DUMP_LDAP sj.us.sczi.com (dn:ou=sj,dc=us,dc=sczi,dc=com) -R -h 
ldap-server -p 389 -D cn=orcladmin -w welcome

DUMP_TNSNAMES

Purpose

Use the command DUMP_TNSNAMES to write the address information defined in the local region to a tnsnames.ora file.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl DUMP_TNSNAMES

From the Oracle Names Control utility:

NAMESCTL> DUMP_TNSNAMES

Arguments

None

Usage Notes

DUMP_TNSNAMES writes the addresses defined in the local region into tnsnames.ora, that is, everything with an address-type record, A.SMD.

The command creates or partially overwrites the tnsnames.ora file. Any entries in the existing tnsnames.ora that are not defined in the Oracle Names servers will remain. Any definitions in tnsnames.ora that are also defined in the Oracle Names servers will be overwritten. Entries that are defined in the Oracle Names servers but not in the tnsnames.ora are added.

Example

NAMESCTL> DUMP_TNSNAMES

EXIT

Purpose

Use the command EXIT to exit from the Oracle Names Control utility.

Prerequisites

The Oracle Names Control utility must be loaded.

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the Oracle Names Control utility:

NAMESCTL> EXIT

Arguments

None

Usage Notes

EXIT has no affect on any Oracle Names servers; it affects only the Oracle Names Control utility.

This command is identical to the QUIT command.

Example

namsctl> EXIT
NL-00851: NAMESCTL finished

FLUSH

Purpose

Use the command FLUSH to instruct the Oracle Names server to clear all remote region information from its local cache checkpoint file, which has a default of ckpcch.ora.

Prerequisites

This command is relevant with an environment with multiple regions where there is authoritative data.

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl FLUSH [onames_server] [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> FLUSH [onames_server] [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. If no names are supplied, then only the current Oracle Names server cache is flushed of the foreign names.

Usage Notes

FLUSH erases all remote data that has been cached. Typically, you should flush the foreign data cache for the following reasons:

A large volume of data changes in the network and the normal time-to-live (TTL) aging mechanism will take too long.
Unidentifiable errors in name resolution of cached foreign data are occurring. Flushing all foreign data from the cache forces it to be looked up again when it is requested the next time.

Names are flushed from the current Oracle Names server. The current Oracle Names server is either the default preferred Oracle Names server or the one set by using the SET SERVER command.

Examples

NAMESCTL> FLUSH
Confirm [yes or no]: yes

FLUSH_NAME

Purpose

Use the command FLUSH_NAME to instruct the Oracle Names server to clear information for a specific region from its local cache checkpoint file, which has a default of ckpcch.ora.

Prerequisites

This parameter is useful for an environment with multiple regions. (In central administration, there is no authoritative data.)

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl flush_name {domain}

From the Oracle Names Control utility:

NAMESCTL> flush_name {domain}

Arguments

[domain]: Specify the domain name.

Usage Notes

FLUSH_NAME erases only data cached from outside the region of the Oracle Names server, that is, non-authoritative data. Data is typically flushed when a name is behaving unusually, suggesting the source copy may have changed.

Names are flushed from the current Oracle Names server. The current Oracle Names server is either the default preferred Oracle Names server or the one set by using the SET SERVER command.

Example

NAMESCTL> FLUSH_NAME mountain.acme.com

HELP

Purpose

Use the command HELP to provide a list of all the Oracle Names Control utility commands or provide syntax help for a particular Oracle Names Control utility command.

Prerequisites

None

Password Required If One Has Been Set:

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl HELP [command]

From the Oracle Names Control utility:

NAMESCTL> HELP [command]

Arguments

[command]: Specify a HELP command. Commands are shown in the following example output.

When you enter a command as an argument to HELP, the Oracle Names Control utility displays information about how to use the command. When you enter HELP without an argument, the Oracle Names Control utility displays a list of all the commands.

Example

NAMESCTL> HELP
The following operations are available:
An asterisk (*) denotes a modifier or extended command:
exit
flush
flush_name
log_stats
ping
query
quitreload
repeat*
reset_stats
restart 
save_config
set*
show
shutdown
start
startup
status
stop 
version

LIST_DELEGATED

Purpose

Use the command LIST_DELEGATED to list all the delegated domains for the root region or a specified domain.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl LIST_DELEGATED [domain]

From the Oracle Names Control utility

NAMESCTL> LIST_DELEGATED [domain]

Arguments

[domain]: Specify the domain name.

Usage Notes

Before exporting data from an Oracle Names server to a directory server, use this command to find out the current domain structure.

Example

NAMESCTL> LIST_DELEGATED
europe.acme.com
asia.acme.com
africa.acme.com

LIST_DOMAINS

Purpose

Use the command LIST_DOMAINS to list all the domains in the root region or subdomains for a specified domain.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system

namesctl LIST_DOMAIN [domain]

From the Oracle Names Control utility:

NAMESCTL> LIST_DOMAIN [domain]

Arguments

[domain]: Specify the domain name.

Usage Notes

Before exporting data from an Oracle Names server to a directory server, use this command to determine the current domain structure.

Example

NAMESCTL> LIST_DOMAINS
com
sczi.com
us.sczi.com
sj.us.sczi.com

LIST_OBJECTS

Purpose

Use the command LIST_OBJECTS to list all the network objects for the root region or a specified domain.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl LIST_OBJECT [-R] [domain]

From the Oracle Names Control utility:

NAMESCTL> LIST_OBJECT [-R] [domain]

Arguments

[-R]: Specify that all authoritative subdomains of the given domain be listed.

[domain]: Specify the domain name.

Usage Notes

Before exporting data from an Oracle Names server to a directory server, use this command to determine the objects stored in a domain.

Example

NAMESCTL> LIST_OBJECTS
partsdb.widgets.acme.com
toolsdb.widgets.acme.com
partsdb.components.widgets.acme.com
sparepartsdb.gadgets.widgets.acme.com

LOAD_TNSNAMES

Purpose

Use the command LOAD_TNSNAMES to load all connect descriptors defined in one or more tnsnames.ora files into an Oracle Names server.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl LOAD_TNSNAMES {directory_path/tnsnames.ora} [...]

From the Oracle Names Control utility:

NAMESCTL> LOAD_TNSNAMES {directory_path/tnsnames.ora}[...]

Arguments

{directory_path/tnsnames.ora}: Specify one or more tnsnames.ora files.

Usage Notes

This command would typically be used once when a site begins using Oracle Names after having used tnsnames.ora files. Run this command once for each region. The names defined during this operation will be defined permanently and will be propagated from one Oracle Names server to all the rest in the region.

Example

NAMESCTL> LOAD_TNSNAMES /oracle9i/network/admin/tnsnames.ora
   Name:                  koala.lab.npd.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  devdd.rdbms.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  envyd.lab.npd.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  stealth.npd.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  null.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  slime.lab.npd.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  felix.hp.us.acme.com 
   Response status:       normal, successful completion 
   Name:                  dtnet1.dec.acme.com 
   Response status:       normal, successful completion 
   Name:                  devds.rdbms.us.acme.com 
   Response status:       normal, successful completion

LOG_STATS

Purpose

Use the command LOG_STATS to log the current set of statistics to the configured log file for that Oracle Names server. The log file has a default of names.log.

Prerequisites

None

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl LOG_STATS [onames_server] [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> LOG_STATS [onames_server] [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. When no names are supplied, then only the statistics for the current Oracle Names server are reset.

Usage Notes

Statistics may be logged if the STATUS command or other behavior indicates some data that you would like to capture in the log. This command does not affect the current log statistics interval.

Example

NAMESCTL> LOG_STATS
Statistics counters logged.

PASSWORD

Purpose

Use the command PASSWORD to set an encrypted password for privileged Oracle Names Control utility commands, such as STOP, RESTART, and RELOAD.

Prerequisites

The Oracle Names Control utility must be loaded.

Password Required If One Has Been Set

Not applicable

Syntax

From the Oracle Names Control utility:

NAMESCTL> PASSWORD [password]

Arguments

Text string matching the value encrypted in the NAMES.PASSWORD parameter in the names.ora file.

Usage Notes

This command does not change a password already established with the NAMES.PASSWORD parameter in the names.ora file. It simply sets an Oracle Names Control utility variable. Then, the value stored is sent from the Oracle Names Control utility with any command request to the Oracle Names server, and the value is compared to that on the Oracle Names server. If they match, then operations requiring passwords are allowed.

Only privileged operations are affected, that is, operations that alter the functioning of the Oracle Names server. Operations such as SHOW or STATUS are not considered privileged, and do not require a password.

The password can either be passed as an argument of the PASSWORD command, or, if no argument is given, you are prompted for the password. Note that the input is not displayed on the screen as it is entered.

When passed over the network, the password is always encrypted, regardless of how it is set.

Examples

NAMESCTL> PASSWORD open_sesame

NAMESCTL> PASSWORD
Enter name server password: names9i

PING

Purpose

Use the command PING to contact an Oracle Names server and display the request/response time.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl PING [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> PING [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. If no names are supplied, then only the current Oracle Names server is pinged.

Usage Notes

Ping ensures that an Oracle Names server is functioning and shows typical response times from the location of the Oracle Names Control utility user to an Oracle Names server.

Example

NAMESCTL> PING nserver.com
Round trip time is 0.04 seconds

QUERY

Purpose

Use the command QUERY to retrieve the contents of a network object stored in the Oracle Names server.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl QUERY object_name [record_type] [modifiers]

From the Oracle Names Control utility:

NAMESCTL> QUERY object_name [record_type] [modifiers]

Arguments

[record_type]: Specify one of the following record types:

A.SMD for a network address
CNAME.SMD for an alias
DL.RDBMS.OMD for a global database link
DLCR.RDBMS.OMD for a global database link qualifier
NS.SMD for an Oracle Names server
V1ADD.NPO.OMD for a SQL*Net Version 1 connect descriptor

[modifier]: Specify one of the following modifier types:

authority: Forces the query to be resolved at the source of the data (in the administrative region where the data is considered local) even if the data is in the local cache. Use this modifier if you suspect that the data has changed at the source.
noforward: Queries for the data, but does not forward the request. When the data is not local and no forward is specified, the query is not be resolved.
trace: Enables a trace of the path to the answer. This is useful whenever you want to find out which Oracle Names servers the request went to.

Usage Notes

QUERY can be used to verify that a defined piece of data can be found, and that the contents are correct.

If this command is used with just a name as a parameter, then Oracle Names server responds with the number of pieces of data with that name, and the time required to complete the operation.

If this command is used with the name and type supplied as arguments, the specific name is looked up and returned to the user.

The QUERY command can take multiple arguments. For example:

QUERY sales.com a.smd authority trace

This command operates on the current Oracle Names server, either the default, or as specified using the SET SERVER command.

Example

NAMESCTL> QUERY bones.dem.medicine a.smd
Total response time:0.04 seconds
Response status:normal, successful completion
Authoritative answer:yes
Number of answers:1
Canonical name:bones.dem.medicine
TTL: 1 day
Alias translations:
    from:bones.dem.medicine
    to: bones.dem.medicine
Answers:
    data type is "a.smd"
        Syntax is ADDR:...(DESCRIPTION=(ADDRESS=
(PROTOCOL=TCP)(Host=bones-pc)
(Port=1521))(CONNECT_DATA=(SERVICE_NAME=bones.dem.medicine)))

QUIT

Purpose

Use the command QUIT to quit the Oracle Names Control utility.

Prerequisites

The Oracle Names Control utility must be loaded.

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the Oracle Names Control utility:

NAMESCTL> QUIT

Arguments

None

Usage Notes

QUIT has no affect on any Oracle Names servers; it affects only the Oracle Names Control utility.

This command is identical to the EXIT command.

Example

NAMESCTL> QUIT
NL-00851: NAMESCTL finished

REGISTER

Purpose

Use the command REGISTER to register a network object to an Oracle Names server.

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system

namesctl REGISTER {object_name} [-t service_type]  
[-d[(DESCRIPTION=](ADDRESS=...)[(CONNECT_DATA=(SERVICE_NAME|SID=service_
name|SID))][)] [-h host] [-l listener_name]

From the Oracle Names Control utility:

NAMESCTL> REGISTER {object_name} [-t service_type]  
[-d[(DESCRIPTION=](ADDRESS=...)[(CONNECT_DATA=(SERVICE_NAME|SID=service_
name|SID))][)] [-h host] [-l listener_name]

Arguments

{object_name}: Specify the object name.

[-t service_type]: Specify the service type of the object:

ORACLE_DATABASE for an Oracle database
ORACLE_LISTENER for a listener
ORACLE_NAMESERVER for an Oracle Names server

Note:
To register an Oracle Names server, use the REGISTER_NS command rather than the REGISTER command.

[-d]: Specify the protocol address of the listener or Oracle Names server object, or complete connect descriptor of the database object, net service name, alias, or global database link.

See Also:

Chapter 5, "Protocol Address Configuration" for further information about protocol addresses and parameters

[-h host]: Specify the host name that the object resides on.

[-l listener_name]: Specify the name of the listener object.

The service type, address description, host, and listener name options are not necessary to make the registration process appear to work. However, they are necessary to make the registration useful. In other words, an object name registered without an address cannot be used.

See Also:

Chapter 5, "Protocol Address Configuration" for further information about protocol addresses and parameters

Note:

The protocol address cannot contain any spaces.

Usage Notes

This command provides a mechanism for registering a service, its type, its hostname, and its address. Both the type of service and the data can be any valid string, but the typical registration has either ORACLE_DATABASE or ORACLE_LISTENER as type of service, and the address as the data.

The object registration is propagated to all other Oracle Names servers in the region.

If the sqlnet.ora file is configured with the parameter NAMES.DEFAULT_DOMAIN to set the same domain name as the database domain, then the database name does not need to be qualified with the domain.

Example

The following example shows the registration of database service sales.us.acme.com.

NAMESCTL> REGISTER sales   -t oracle_database -d (DESCRIPTION=(ADDRESS= 
(PROTOCOL=TCP)(HOST=sales-server)(PORT=1575)) (CONNECT_DATA=(SERVICE_
NAME=sales.us.acme.com)))

REGISTER_NS

Purpose

Use the REGISTER_NS command to define an Oracle Names server and its authoritative domain.

Prerequisites

None

Password required if one has been set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl REGISTER_NS {onames_server}{(ADDRESS=...)}{domain}

From Oracle Names Control utility:

NAMESCTL> REGISTER_NS {onames_server}{(ADDRESS=...)}{domain}

Arguments

{onames_server}: Specify the Oracle Names server name.

{(ADDRESS=...)}: Specify the Oracle Names server protocol address.

{domain}: Specify the domain name.

Usage Notes

This command provides a mechanism for registering an Oracle Names server as an authoritative server for a given domain. The command adds a network session record type, NS.SMD, for the Oracle Names server to the domain, and provides the Oracle Names server with an address record, A.SMD.

This command will fail if either the domain exists and has non-NS records or the Oracle Names server exists and has a type of service record that is other than 'ORACLE_NAMESERVER'.

Ordinarily, the Oracle Names servers maintain their own data by registering themselves when they start. This command is provided as a manual way to manage domain and Oracle Names server data if for some reason the Oracle Names server cannot. This may occur if the region database tables are set up as read-only for security reasons.

If the Oracle Names servers are not registering themselves, then use this command to define the region topology data. Each Oracle Names server in the region should be defined using this command for each top-level domain in the region. Usually, the top level consists of a single parent domain, for example, acme.com. However, a region may also have multiple sibling parent domains, for example, a region covering North America would have US, CA, and MX as its top-level parent domains.

Note the regions which were defined using the Oracle Network Manager in SQL*Net version 2 have NS.SMD records defined for every domain in the administrative region, but in Oracle Net only the top-level parent domains need to have ns.smd records defined for each server in the region.

Use the Oracle Names Control utility DELEGATE DOMAIN command to define Oracle Names servers which are delegation points for subregions.

Use the NAMES.DOMAIN_HINTS parameter in the names.ora file to provide data about any other Oracle Names servers in foreign regions.

Example

NAMESCTL> REGISTER_NS  namesrv1 
(ADDRESS=(PROTOCOL=tcp)(HOST=namesvr1)(PORT=1575))
Total response time:   7 minutes 59.14 seconds
Response status:       normal, successful completion

RELOAD

Purpose

Use the command RELOAD to force the Oracle Names server to check immediately for data changes in its administrative region. If there are any changes, then the Oracle Names server reloads all database service names, net service names, global database links, and aliases.

Prerequisites

None

Password Required If One Has Been Set

Yes. If a password is set, then issue then the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl RELOAD [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> RELOAD [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. If no names are supplied, then only the current Oracle Names server is reloaded.

Usage Notes

All Oracle Names servers load their data directly from the database specified by the NAMES.ADMIN_REGION parameter in the names.ora file.

In an environment with multiple regions, RELOAD affects only the data for the current administrative region. All foreign data in the cache is unchanged.

Example

NAMESCTL> RELOAD
Server reloaded.

REORDER_NS

Purpose

Use the command REORDER_NS to create the file that lists local Oracle Names servers and their protocol addresses.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl REORDER_NS [(ADDRESS=...)]

From the Oracle Names Control utility:

NAMESCTL> REORDER_NS [(ADDRESS=...)]

See Also:

Chapter 5, "Protocol Address Configuration" for further information about protocol addresses and parameters

Arguments

[(ADDRESS=...)]: Specify an optional Oracle Names server address to be used as the initial Oracle Names server to contact.

Usage Notes

This command generates the file which defines Oracle Names server names and addresses to enable clients to contact Oracle Names servers for name lookup.

The REORDER_NS command performs the following tasks:

Searches for the first Oracle Names server in the following order:
1. A preferred Oracle Names server configured in the sqlnet.ora file with the NAMES.PREFERRED_SERVERS parameter
2. A well-known Oracle Names server
3. A local Oracle Names server configured with TCP/IP on port 1575
Sends a query for all the Oracle Names servers in the local region
Sends a ping to each of these Oracle Names servers
Sorts the list of Oracle Names servers by increasing order of response time
Writes an Oracle Names server list with the sorted list of names and addresses

Example

NAMESCTL> REORDER_NS (ADDRESS=(PROTOCOL=tcp)(HOST=namesrv-server)(PORT=1575))

REPEAT

Purpose

Use the command REPEAT to perform QUERY, REGISTER, TIMED_QUERY, or UNREGISTER multiple times to compute average return rates.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system prompt:

namesctl REPEAT {number} QUERY|REGISTER|TIMED_QUERY|UNREGISTER [record_type]

From the Oracle Names Control utility:

NAMESCTL> REPEAT {number} QUERY [record_type]

Arguments

{number}: Specify an integer

[record_type]: Specify one of the following record types:

A.SMD for a network address
CNAME.SMD for an alias
DL.RDBMS.OMD for a global database link
DLCR.RDBMS.OMD for a global database link qualifier
NS.SMD for an Oracle Names server
V1ADD.NPO.OMD for a SQL*Net Version 1 connect descriptor

Usage Notes

This command is useful for understanding the average response time over a number of requests.

Do not specify too large a number here; while the number of iterations are occurring, the Oracle Names Control utility cannot perform any other operation.

Example

NAMESCTL> REPEAT 10 QUERY manatee a.smd
Number of requests: 10
Average response time: 0.01 seconds
Minimum response time: 0.01 seconds
Maximum response time:0.04 seconds
Total response time:0.14 seconds
Response status:normal, successful completion
Authoritative answer:yes
Number of answers: 1
TTL: 1 day
Answers:
    data type is "a.smd"
        Syntax is ADDR:(DESCRIPTION=(ADDRESS=
(PROTOCOL=TCP)(Host=salmon)
(Port=1522))(CONNECT_DATA=(SID=otter)))

RESET_STATS

Purpose

Use the command RESET_STATS to reset the Oracle Names server statistics to the original values of the Oracle Names server at startup.

Prerequisites

None

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl RESET_STATS [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> RESET_STATS [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. If no names are supplied, then only the current statistics for the Oracle Names server are reset.

Example

NAMESCTL> RESET_STATS
Confirm [yes or no]: yes
Server statistics reset.

RESTART

Purpose

Use the command RESTART to initiate a reset of an Oracle Names server to its original state at startup.

Prerequisites

None

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system prompt:

namesctl RESTART [onames_server] [...]

From the Oracle Names Control utility:

NAMESCTL> RESTART [onames_server] [...]

Arguments

[onames_server]: Specify zero or more Oracle Names servers separated by a space. If no names are supplied, then only the current Oracle Names server is restarted.

Usage Notes

RESTART is the same as STARTUP, except that you use it when the Oracle Names server is already running.

Data is reloaded, statistics are reset, and all foreign data is flushed. Valid foreign cache data, that is, data with a TTL greater than 0, is retrieved from the checkpoint files.

Example

NAMESCTL> RESTART
Confirm [yes or no]: yes
Server restarted.

SAVE_CONFIG

Purpose

Use the SAVE_CONFIG command to compare the current configuration state of the Oracle Names server, including trace level, trace file, trace directory, and logging to the names.ora file. Any changes are stored in names.ora, preserving formatting, comments, and case as much as possible.

Password Required If One Has Been Set

Yes. If a password is set, then issue the SET PASSWORD command prior to this command.

Syntax

From the operating system:

lsnrctl SAVE_CONFIG

From the Oracle Names Control utility:

LSNRCTL> SAVE_CONFIG

Arguments

None

Example

NAMESCTL> SAVE_CONFIG  
Server saving the config file now

SET

Purpose

Use the SET command to alter the parameter values for the Oracle Names server. These changes remain in effect until the Oracle Names is stopped. To make the changes permanent, use the SAVE_CONFIG, SET SAVE_CONFIG_ON_STOP, or SET SAVE_CONFIG_INTERVAL commands to save changes to the names.ora file.

Prerequisites

None

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

NAMESCTL SET [parameter]

From the Oracle Names Control utility:

namesctl> SET [parameter]

Arguments

[parameter]: Specify a SET parameter to modify its configuration setting. Parameters are shown in the example output.

When you enter SET without an argument, the Oracle Names Control utility displays a list of all the parameters.

Example

NAMESCTL> SET
The following operations are available after set
An asterisk (*) denotes a modifier or extended command:
cache_checkpoint_interval
default_domain
forwarding_available
log_file_name
log_stats_interval
NAMESCTL_trace_level
password
requests_enabled
reset_stats_interval
save_config_interval
save_config_on_stop
server
trace_file_name
trace_level

SET CACHE_CHECKPOINT_INTERVAL

Purpose

Use the command SET CACHE_CHECKPOINT_INTERVAL to specify the time, in seconds, of how often to save all collected information about remote regions to the local cache file. By default, the cache checkpoint file name is ckpcch.ora.

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the operating system:

namesctl SET CACHE_CHECKPOINT_INTERVAL [time]

From the Oracle Names Control utility:

NAMESCTL> SET CACHE_CHECKPOINT_INTERVAL [time]

Arguments

{time}: Specify the number of seconds.

For example, to increase the interval to 36 hours, set the following:

NAMESCTL> SET CACHE_CHECKPOINT_INTERVAL 129600

Usage Notes

Minimum Value: 10

Maximum Value: 259200 (3 days)

Default Value: 0 (disabled)

Example

NAMESCTL> SET CACHE_CHECKPOINT_INTERVAL 12

SET DEFAULT_DOMAIN

Purpose

Use the command SET DEFAULT_DOMAIN to set the domain from which the Oracle Names Control utility most often looks up names resolution requests. The domain set is used for the duration of the session, ignoring the NAMES.DEFAULT_DOMAIN parameter configured in the sqlnet.ora file.

Prerequisites

The Oracle Names Control utility must be loaded.

Password Required If One Has Been Set

No. If a password is set, then the SET PASSWORD command does not need to be issued prior to this command.

Syntax

From the Oracle Names Control utility:

NAMESCTL> SET DEFAULT_DOMAIN [domain_name]

3 Oracle Names Control Utility

Oracle Names Control Utility Overview

SET and SHOW Commands of the Oracle Names Control Utility

Distributed Operations

Oracle Names Server Security

Confirmation Mode in the Oracle Names Control Utility

Oracle Names Control Utility Commands

DELEGATE_DOMAIN

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Examples

DOMAIN_HINT

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Examples

DUMP_ALIAS

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Examples

DUMP_LDAP

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Examples

DUMP_TNSNAMES

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Example

EXIT

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Example

FLUSH

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Examples

FLUSH_NAME

Purpose

Prerequisites

Password Required If One Has Been Set

Syntax

Arguments

Usage Notes

Example

HELP

Purpose

Prerequisites

Password Required If One Has Been Set:

Syntax

Arguments

Example

LIST_DELEGATED

Purpose

3
Oracle Names Control Utility