Troubleshooting Connectivity
How Connection Between the Application and DBMS Server Is Established
For queries to be processed, applications must establish a connection to the DBMS Server through Ingres Net. When an application issues a query, the query is sent to the DBMS Server for execution. The server executes the query and returns data to the application.
For a client to connect to a server through Ingres Net, many internal connections must be made.
When the application, the DBMS Server, and the database reside on the same instance, establishing a connection is a short process:
1. The application program connects to the local Name Server (iigcn) and requests the listen address of the local DBMS Server process.
2. The Name Server returns this information to the application, which thereafter communicates directly with the DBMS Server through that address.
When the application and DBMS Server are on separate instances, the process has more steps:
1. The application finds the local Name Server (iigcn) listen address and talks to the local Name Server to request remote access.
2. The local Name Server passes the listen address of the local Communications Server (iigcc) and the listen address of the remote Communications Server (iigcc) back to the application. (The local Name Server (iigcn) stored the remote Communications server’s listen address when you ran netutil on the local instance.)
3. The application connects to the local Communications Server, passing it the remote Communications Server’s listen address as part of the remote access request.
4. The local Communications Server connects to the remote Communications Server and requests a connection to a DBMS Server on that remote instance.
5. The Communications Server on the remote instance finds the listen address of the Name Server on the remote instance. The Communications Server requests connection information from the Name Server, passing the name of the database for which a connection is requested.
6. The remote Name Server returns the listen address of a DBMS Server that is capable of servicing a request for connection to the target database.
7. The remote Communications Server connects to the DBMS Server on the remote instance.
When these steps are completed, a “virtual connection” has been established between the application and the DBMS Server.
Where Ingres Net Information Is Stored
Ingres Net configuration values are stored in either of the following:
config.dat file
Stores Ingres Net configuration parameters, which can be changed using Configuration-By-Forms or Configuration Manager.
Name Server database
Stores remote access information, which can be entered using the netutil utility.
config.dat--Store Net Configuration Values
The following Ingres Net configuration parameters, stored in config.dat, can be viewed and changed using the Configuration Manager (vcbf) or Configuration-By-Forms (cbf) utility. The default values are assigned during installation.
Note: The Net Server is the Communications Server.
Name Server Database--Store Remote Access Information
The Name Server database is an internal database used by the Name Server (iigcn). The Name Server database contains the information required for remote access, such as remote node names, listen addresses, login accounts and passwords, virtual node names, and local and remote Installation Passwords. This information can be entered in the Name Server database using the netutil utility.
In a client/server configuration, this database contains one file called iiname.all and one or more "nodename" files for each client node and for the local node. For example:
iiname.all
IIINGRES_nodename1
IICOMSVR_nodename1
IISTAR_nodename1
IINODE_nodename1
IILOGIN_nodename1
IIIUSVR_nodename1
IIDB2UDB_nodename1
IIORACLE_nodename1
IIRDB_nodename1
IIRMS_nodename1
IILTICKET_nodename1
IIRTICKET_nodename1
IIINGRES_nodename2
IICOMSVR_nodename2
IISTAR_nodename2
IINODE_nodename2
IILOGIN_nodename2
IIIUSVR_nodename2
IIDB2UDB_nodename2
IIORACLE_nodename2
IIRDB_nodename2
IIRMS_nodename2
IILTICKET_nodename2
IIRTICKET_nodename2
A unique set of files is created for each node registered as an Ingres Net client.
In the cluster environment, the Name Server database has only one file of each type. For example:
iiname.all
INGRES
COMSVR
STAR
NODE
LOGIN
IUSVR
DB2 UDB
ORACLE
RDB
RMS
LTICKET
RTICKET
All the nodes in an Ingres Cluster Solution instance share the same files.
The files in the Name Server Database are as follows:
iiname.all
Contains a list of all of the types of servers that the instance is expected to manage. The possibilities are DBMS servers, Communications servers, and Star servers.
IIINGRES_nodename
Contains the GCA listen addresses of all the DBMS servers registered with the Name Server (iigcn) on the specified node.
The file is written when the DBMS Server starts and is cached when the node's (identified by nodename) Name Server starts.
IICOMSVR_nodename
Contains the GCA listen address of the Communications Server (iigcc) on the specified node (identified by nodename). The file is written when the local Communications Server starts and is cached when the local Name Server starts.
IISTAR_nodename
Contains the GCA listen address of the Star Server on the specified node (identified by nodename). The file is written when the Star Server starts and is cached when the nodename’s Name Server starts.
IINODE_nodename
Contains the connection data entries established for the specified node (identified by nodename) by running netutil, Network Utility (ingnet) or Visual DBA from that node. The file is written whenever you select the “create” option to add a connection data entry for an existing vnode. The file is cached when the nodename’s Name Server starts.
IILOGIN_nodename
Contains the remote user authorizations set up at the specified node (identified by nodename) by running netutil, Network Utility (ingnet) or Visual DBA from that node. The file is written whenever you add a remote user authorization. It is cached when the nodename’s Name Server starts.
Causes of Connectivity Problems
You can trace most network connectivity problems to one of the following causes:
• The network or the network protocol is not properly installed
• The Name Server (iigcn) or Communications Server (iigcc) process is not running
• Vnode entries are incorrect
• There are port connection problems
• There are problems with the Ingres Net files
How You Diagnose Connectivity Problems
Often, the most difficult task in problem solving is determining the origin of the problem. Sometimes the circumstances of the problem point to a particular cause. For example, if only one user on a node is experiencing an Ingres Net connection problem, that user’s vnode entries are probably incorrect. Some problems, however, leave more ambiguous clues.
To determine the origin of a problem, follow these steps:
1. Examine the error file, errlog.log. Vector logs DBMS error messages, Ingres Net error messages, and Communications Server startup and shutdown messages to this log.
The default location for the errlog.log file is:
Windows: %II_SYSTEM%\ingres\files\errlog.log
Linux: $II_SYSTEM/ingres/files/errlog.log
Often the error message provides sufficient information to determine the origin of the problem.
2. Examine any of the optional logs or tracing facilities, if set up in your installation.
3. Perform the General Ingres Net Installation Check described next if examining the error messages does not pinpoint the origin of the problem.
If you are having password or other security or permission problems with Ingres Net, use the procedure in Security and Permission Errors to resolve them.
General Net Installation Check
The Ingres Net installation check is a diagnostic procedure that checks your installation to determine the following:
• Whether the problem is Ingres Net-related
• Whether the iigcn and iigcc processes are running
• Whether the network protocol software is working
How You Check Net Installation on Windows
If you are experiencing a problem and cannot determine its source, use this diagnostic procedure as a starting point:
1. Verify that your network protocol is functioning.
a. Use the ping command to connect between machines to verify that basic TCP/IP networking is working.
b. On both the client and the server, verify that TCP/IP is properly installed and configured. Do this by attempting to connect to the default localhost (or loopback) listen address from each machine. Type one of the following commands to loop back to your own machine using the network:
• ping localhost
• ping 127.0.0.1
• ping ::1 (if TCP/IP version 6 enabled)
If either “a” or “b” fails, the problem is with the underlying network. Contact your network administrator.
2. If the remote node is a Linux machine, verify that you can connect to the target database on the remote node when you are logged in directly to the remote node.
a. Use telnet to log in to the remote node from your local node.
b. Enter a command that connects you to the database. For example:
sql database_name
If you cannot connect to the database even when logged in directly to the remote node, the problem is something other than Ingres Net.
If you can connect this way, but cannot connect when you are Using Net to log in to the remote node and connect (through the syntax sql vnode_name::database_name), it is an Ingres Net problem. Proceed with Step 3.
3. Check that the iigcc process is registered with the Name Server:
a. Enter iinamu at the operating system prompt.
b. Type show comsvr.
If you receive no output from the show comsvr command, this means that no Communications Server is registered with the Name Server.
4. Check that configuration parameters such as local_vnode and the Communications Server listen address are correctly set. These parameters can be viewed and, if necessary, changed using the Configuration Manager (vcbf) or Configuration-By-Forms (cbf) utility.
5. Check the II_GCNxx_PORT environment variable where xx is the instance ID. It must be visible only when using the ingprenv utility. It must never be visible when using the Linux commands env or printenv. II_GCNxx_PORT must not be part of your local operating system environment. If it is set in the local environment, it overrides their proper settings in the Vector symbol table.
You must be the installation owner to take corrective action.
How You Check Net Installation on Linux
If you are experiencing a problem and cannot determine its source, use this diagnostic procedure as a starting point:
1. Verify that your network protocol is functioning.
a. Use the rlogin and/or telnet commands to connect between machines to verify that basic TCP/IP networking is working.
b. On both the client and the server, verify that TCP/IP is properly installed and configured. Do this by attempting to connect to the default localhost (or loopback) listen address from each machine. Type the following command to loop back to your own machine using the network:
ping localhost -c
where c is equal to 1 or 2.
The login messages that follow the command reveal whether you are connected to your own machine (the name of the machine can be embedded in the messages). If they do not, you can log in and issue the hostname command to display the name of the machine to which you are connected.
If either “a” or “b” fails, the problem is with the underlying network. Contact your network administrator.
2. Verify that you can connect to the target database on the remote node when you are logged in directly to the remote node.
a. Use telnet, rlogin, or your site’s network server bridge software to log in to the remote node from your local node.
b. Enter a command that connects you to the database. For example:
$ sql database_name
If you cannot connect to the database even when logged in directly to the remote node, the problem is something other than Ingres Net.
If you can connect this way, but cannot connect when you are Using Net to log in to the remote node and connect (through the syntax sql vnode_name::database_name), it is an Ingres Net problem. Proceed with Step 3.
3. To verify that the Communications Server (iigcc) and Name Server (iigcn) processes are running on your local node, use the ps command. This command shows the status of all currently running processes. Also check the processes on the remote node.
4. Check that the iigcc process is registered with the Name Server:
a. Enter iinamu at the operating system prompt.
b. Type show comsvr.
If you receive no output from the show comsvr command, this means that no Communications Server is registered with the Name Server.
5. Check that configuration parameters such as local_vnode and the Communications Server listen address are correctly set. These parameters can be viewed and, if necessary, changed using the Configuration Manager (vcbf) or Configuration-By-Forms (cbf) utility.
6. Check the II_GCNxx_PORT environment variable where xx is the instance ID. It must only be visible using the ingprenv utility. It must never be visible using the Linux commands env or printenv. II_GCNxx_PORT must not be part of your local Linux shell environment. If it is set in the local environment, it overrides their proper settings in the Vector symbol table.
You must be the installation owner (who by default has Vector user privileges) to take corrective action.
Connection Errors
Connection errors can occur for a variety of reasons. For example, a failure in any of the internal connections described in
How Connection Between the Application and DBMS Server Is Established results in a connection error.
How connection errors are reported depends on where the failure occurs. If failure occurs:
• At the local instance, errors are reported directly to the user interface program or the application.
• Between the local and remote instances, for example, when attempting to connect from the local Communications Server to the remote Communications Server, errors go to the local errlog.log file as well as to the application.
• At the server installation, errors are reported to both the local and remote errlog.log file and to the application.
Local Connection Errors
Each Communications Server has a GCA and GCC listen address. The GCA listen address is the server’s connection to local processes and is known only to the local Name Server (iigcn). The GCC listen address is the server’s connection to the network and is known to all nodes in the network. These listen addresses are stored separately.
The GCA address is stored at runtime in an IICOMSVR file in the Name Server database. You can obtain this address using the iinamu utility. Do not attempt to view these files directly. For more information about iinamu, see the “Command Reference” chapter in the User Guide.
The GCC address is stored in the config.dat file when the installation is configured. To view or change the GCC address, use the Net Server Protocol Configuration screen in the Configuration-By-Forms (cbf) utility, or the Net Server Protocols page in Configuration Manager (vcbf).
When the Communications Server starts up, it must be able to obtain the use of the network (GCC) listen address. If the Communications Server cannot use this listen address because the operating system has allocated the address to another process, the Communications Server cannot listen on that protocol. This problem can occasionally arise if the installation is not started from the machine boot file.
How You Resolve Remote Connection Errors
When you cannot establish a remote connection, use this procedure to diagnose the problem:
1. Check the errlog.log for error messages.
2. If that does not identify the problem, follow the procedure for your protocol in the General Net Installation Check section of this chapter. This procedure tells you if your network and protocol are working properly and if the Name Server (iigcn) and Communications Server (iigcc) processes are working properly.
3. If the problem remains unidentified after you have looked at the error messages and performed the installation check, use the following procedure to verify that your netutil connection data entry contains the correct listen address.
a. From the local instance, check the connection data for the remote instance. Note the listen address specified in the netutil Connection Data table.
b. From the remote instance, check to see which GCC listen address the remote instance’s Communications Server is using. You can find this information in the Net Server Protocol Configuration screen in the Configuration-By-Forms (cbf) utility, or the Net Server Protocols page in Configuration Manager (vcbf).
c. If the listen address found Step a does not match the listen address found in Step b, correct the problem by re-registering the remote instance’s GCC listen address. Do this from the local instance, using netutil to edit the incorrect entry. For procedures for adding, deleting, and changing a vnode definition, see the chapter "Creating Server Connection Definitions."
How You Resolve Net Registration Problems
To resolve net registration problems, use this procedure:
1. Use the General Net Installation Check to verify that your installation is properly installed and working.
2. Check that your connection data entries and remote user authorizations are correct.
The utilities used to set up connection data and remote user authorizations (Network Utility, Visual DBA, or netutil) can test a connection, but you must explicitly choose the Test operation from a menu. If you did not test the connection after entering, adding, or editing connection data or remote user authorizations, the information can be incorrect.
3. Check that the required connection data and remote user authorizations for the target installation exist. If they are present, check the following:
• That all vnode names and user (account) names are spelled correctly
• That the proper network protocol has been specified
• That listen addresses and network addresses are correct
Note: End users check their private entries. A user with the SECURITY privilege (typically a system administrator) checks another user’s private entries by using the -u command flag in netutil to impersonate that user. Users can also perform this task using Network Utility and Visual DBA.
Any user can check global entries, however if corrections are required, they must be made by a user with the GCA privilege NET_ADMIN (typically the system administrator).
4. If you are experiencing problems connecting to a distributed database, make sure that the connection data and remote user authorizations required by Ingres Star have been entered on the Star Server installation. For more information, see the Ingres Star User Guide.
Security and Permission Errors
Ingres Net encrypts the password entered in netutil and compares it with the encrypted password in “/etc/passwd” (or your machine’s similar password file). If the two do not match, an error is returned.
How You Resolve Security Problems (Linux)
If you are having password or other security/permission problems in Ingres Net, use the following procedure:
1. Verify that you can log in to the remote machine directly. If you cannot, you do not have the right password.
2. Using netutil, re-enter the remote user authorization.
3. If you are running NIS (“yellow pages”), the account’s correct password will be in the yellow pages password file (/etc/yppasswd) rather than in /etc/passwd. Add the following string to the end of /etc/passwd file to tell Ingres Net to look in /etc/yppaswd for the encrypted password:
+::0:0:::
4. If you have additional security such as C2 security enabled on the target machine, you must verify that the ingvalidpw executable exists in $II_SYSTEM/ingres/bin by typing:
$ ls -l $II_SYSTEM/ingres/bin/ingvalidpw
This executable is required to make the password in the secure area readable by Vector.
Note: Not all Vector releases on Linux use ingvalidpw to enforce C2 security. If the ingvalidpw executable is required for your release, it will be documented in the Readme file for your platform.
5. If the ingvalidpw executable exists:
a. Verify that it is owned by root. If not, log in as root and issue the command:
$ chown root ingvalidpw
b. Verify that it has the “set uid” bit set. If not, issue the command:
$ chmod 4711 ingvalidpw
c. Verify that the Vector variable II_SHADOW_PWD is set to the full path to the ingvalidpw executable. Type:
$ ingprenv | grep II_SHADOW_PWD
The ingprenv utility displays the II_SHADOW_PWD variable.
6. If the ingvalidpw executable is not installed, create it using the mkvalidpw script.