Troubleshooting - DB & Login
The N2C5 platform does not have its own database. It uses the NCC SMF database for all database storage. The NCC database is used for the following N2C5 UI features.
- Subscriber Information (except "Wallet Details")
- Subscriber EDR Listings
- Subscriber Credit Card List
- Voucher Information (except "Voucher State")
- Rating Management
- Geography Management
The connection to the SMF database is made using the OracleDB SQL*Net protocol, as implemented by the DBD::Oracle driver. The DBD::Oracle driver is a wrapper layer written around the libclntsh.so shared library. The DBD::Oracle driver uses a connection string defined in the N2C5 Jarvis application configuration. An example configuration is:
<database name="smf" connect="dbi:Oracle:host=10.42.2.154;sid=SMF;port=1521" username="smf" password="<smf-password>"/>
The "host=" and "port=" parameters refer to the SMF database instance Oracle Listener process.
If you are getting a complete failure to connect to the SMF database, then check the following:
- Ensure that the configured listener host name/IP address is correct.
- Ensure that the configured listener port number is correct.
- Ensure that the configured SID is correct.
- Ensure that the configured "smf" password is correct.
- Ensure that the OracleDB instance is actually running.
- Ensure that the Oracle Listener process is actually running.
- Ensure that the Oracle Listener has not reached its connection limit.
- Ensure that the listener host/port can be reached via TCP and is not firewall blocked.
Listener SQL*Net Connection
It is not merely sufficient that the N2C5 platform can reach the configured host address. It must also be able to resolve the name by which the SMF platform identifies itself. This is a common problem when performing the initial DB connection setup.
Specifically, the SQL*Net handshake process works as follows:
- N2C5 makes a setup request to the Oracle Listener hostname/IP configured in the "host=" segment of the DBI connection string.
- The Listener will reply with a per-session hostname and port number.
- N2C5 makes a data connection request to the supplied host name and port number.
The per-session hostname supplied by Oracle is determined by the setup of the Oracle NCC SMF platform, and is not at all required to be the same as the initial setup hostname.
The N2C5 platform must be able to resolve (via DNS or /etc/hosts) the hostname returned by the Oracle Listener. This name will be one of the hostnames by which the SMF is known. In a production system, the SMF will typically have multiple hostnames in order to support its multiple IP addresses. It may be necessary to use Wireshark to capture the setup messages in order to determine exactly which hostname is being supplied by the Listener.
SMF Login Authentication
The N2C5 user authentication process can be configured to use either:
- The NCC SMF User Table (SMF_USER)
For notes in configuring LDAP/ActiveDirectory user integration, please refer to the relevant Jarvis Login Module configuration notes in the Jarvis Documentation.
For sites which use SMF User Integration, the N2C5 performs the following authentication process at the start of each session.
- Create a primary connection to Oracle as the user "smf" with the configured password. (Failure
- Check that the user-supplied username exists in the SMF_USER database table.
- (If configured to do so) Check that the user-supplied username is SCREENS_USER.
- Check that the user-supplied username is not locked (LOCK_REASON must be NULL).
- Create a secondary connection to Oracle with the user-supplied username and password.
Because of a quirk in the NCC auditing system, this secondary connection will always fail on trigger SMF_USER_ALD. The SMF_USER_ALD trigger performs a "program" check which is incompatible with the Oracle-supplied client library libclntsh.so.
The login process will examine how the login check failed, and will produce the following output to debug. On correct password, the debug output is:
Login succeeded (password correct) but was blocked by SMF_USER_ALD.
On wrong password, the debug output is:
Login failed (wrong password/username).
Note: This login process is relatively slow. For performance reasons, it is only performed when the user's session is created. Once successful, the login check is not required again until the session expires.
The following generic DBD::Oracle Linux Troubleshooting Guide may also be useful.