| Like other Net8 components , Connection Manager has a control utilityin this case, Connection Manager Control (the executable name is cmctl ). Use cmctl to start and stop Connection Manager, check status, examine current connections, and to perform the other tasks described in this section. The command set implemented by cmctl is similar to, but more limited than, that implemented by namesctl and lsnrctl . As with the other two utilities, you can pass commands to cmctl on the command line, or you can enter them at the cmctl command prompt. While it's not well documented, you can even use the @ command from within cmctl to execute commands from a text file. 9.5.1 Starting and Stopping Connection Manager You start and stop Connection Manager using the Connection Manager Control utility's START and STOP commands. The following example shows cmctl being invoked, and then the START command being used to start Connection Manager: [oracle@donna oracle]$ cmctl CMCTL for Linux: Version 8.1.6.0.0 - Production on 14-AUG-2000 09:57:26 (c) Copyright 1998, 1999, Oracle Corporation. All rights reserved. Welcome to CMCTL, type "help" for information. CMCTL> START ADMIN Status: (STATUS=(VERSION=8.1.6.0.0)(STARTED=14-AUG-2000 09:57:28)(STATE=RUNNING)) CMAN Status: (STATUS=(VERSION=8.1.6.0.0)(STARTED=14-AUG-2000 09:57:30)(STATE=running)) CMCTL> In response to the START command, Connection Manager Control has started both the admin process and the gateway process. Then it displays the status of each so you can verify that they are running. 9.5.1.1 Stopping Connection Manager Use the SHUTDOWN command to stop the Connection Manager processes. The syntax looks like this: SHUTDOWN [NORMAL ABORT] The NORMAL and ABORT options control how abruptly Connection Manager shuts down. When you perform a normal shutdown, Connection Manager stops accepting new connections, but it continues to relay existing connections. Only when all existing users have disconnected will the Connection Manager processes be stopped . A SHUTDOWN ABORT causes the Connection Manager processes to stop immediately. This has the effect of forcibly disconnecting all database users who are connected through the particular Connection Manager instance that you just aborted. A normal shutdown is the default, but it may take a while to complete because it won't forcibly disconnect any users.  | Two other commands, STOP and STOPNOW, can also be used to stop Connection Manager. These commands are obsolete in Oracle8 i , but have been retained for compatibility purposes. Oracle recommends the use of SHUTDOWN. STOP is similar to SHUTDOWN NORMAL; STOPNOW is equivalent to SHUTDOWN ABORT. | | 9.5.1.2 Starting and stopping just one process It's possible to start and stop just one of the two Connection Manager processes, although this functionality appears to have no practical value in the current release of Net8. To specify a particular process to start or stop, use one of the parameters described in Table 9.3. Table 9.3. Parameters to Start or Stop Just One Process | Parameter | Description | Available for These Commands | | cm | Starts or stops only the gateway process (CMGW). | START, STOP, STOPNOW | | adm | Starts or stops only the admin process (CMADMIN). | START, STOP, STOPNOW | | cman | Starts or stops both processes. | START, SHUTDOWN, STOP, STOPNOW | The cman parameter is always the default, and it's the only option available with the SHUTDOWN command that Oracle recommends over STOP and STOPNOW. Using cm with STOP or STOPNOW always results in both processes being stopped. You can stop the admin process while leaving the gateway process running, but you can't stop just the gateway process and leave the admin process running by itself. The gateway process provides the core functionality of Connection Manager. It's the process responsible for relaying connections from client to server. While it is possible to start just the gateway process and use the core functionality of Connection Manager, we don't see any clear benefit in doing that. In normal operations, we think you should always start both processes. The ability to start just one of the processes seems best reserved for cases in which one process fails and needs to be restarted. 9.5.2 Viewing Statistics and Other Information Connection Manager Control implements useful commands that allow you to check Connection Manager's status, and peek in on what's happening. These commands include the following: - STATUS
-
Verifies the current status of the processes - STATS
-
Provides some key statistics related to Connection Manager's operation - RELAYS
-
Lists the current connections being relayed through Connection Manager - SHOW RULES
-
Lists the current set of access control rules 9.5.2.1 Connection Manager status Use the STATUS command to check on the current status of the Connection Manager processes. You can see if they are running, and for how long. Here's an example: CMCTL> STATUS CMAN Status: (STATUS=(VERSION=8.1.6.0.0)(STARTED=14-AUG-2000 10:40:15)(STATE=running)) ADMIN Status: (STATUS=(VERSION=8.1.6.0.0)(STARTED=14-AUG-2000 10:40:13)(STATE=RUNNING)) CMCTL> SET DISPLAYMODE VERBOSE Current display mode is VERBose CMCTL> STATUS STATUS of the cman ----------------------------------------- CMAN Version 8.1.6.0.0 Start-up time 14-AUG-2000 10:40:15 Current state running STATUS of the cman_admin ----------------------------------------- ADMIN Version 8.1.6.0.0 Start-up time 14-AUG-2000 10:40:13 Current state RUNNING The first STATUS command in this example used the default display mode of COMPATIBLE, while for the second example the display mode was switched to VERBOSE. The verbose output is more readable, but both provide the same information. 9.5.2.2 Connection Manager statistics The STATS command provides you with some key statistics relative to Connection Manager's operation: CMCTL> STATS CMAN Status: (STATISTICS=(TOTAL_RELAYS=2)(ACTIVE_RELAYS=2)(MOST_RELAYS=2)(OUT_OF_ RELAY=0)(TOTAL_REFUSED=0)) CMCTL> SET DISPLAYMODE VERBOSE Current display mode is VERBose CMCTL> STATS STATISTICS of CMAN ----------------------------------------- Total number of connections handled 2 Number of currently active relays 2 Peak active relays 2 Total refusals due to max_relays exceeded 0 Total number of connections refused 0 As with the STATUS command, the information provided by STATS is much more readable if the VERBOSE display mode is used. The statistic descriptions are fairly self-explanatory. The "number of currently active relays" statistic refers to the number of users currently connected through Connection Manager. The term "relays," while technically correct, is certainly less personal than "users." Bear in mind, especially if you are going to do a SHUTDOWN ABORT, that each "relay" is likely to be a flesh-and-blood " user ." The "total refusals due to max_relays exceeded" count is worth watching, because it will tell you if too many users are sharing one Connection Manager instance. If the number of such refusals is high and consistently climbing, then you should do one of two things: -
Increase the value of MAX_RELAYS in the Connection Manager Profile -
Create another Connection Manager instance on another node, and point some of your users to that Your choice should depend on how loaded your current Connection Manager instance is. 9.5.2.3 Examining relays If you're curious about the connections currently being made through a Connection Manager instance, you can use the SHOW RELAY command to view some interesting information. First, use SHOW RELAY ACTIVE, as shown in this example, to see a list of the relays that are currently active: CMCTL> SHOW RELAY ACTIVE Active Relays ----------------------------------------- 0000 0001 This doesn't give you a lot of information. All relays are numbered, and SHOW RELAY ACTIVE just gives you a list of valid relay numbers . | | You can abbreviate SHOW RELAY ACTIVE to SHOW RELAY ACT. | | Things get more interesting when you issue the SHOW RELAY command followed by a specific relay number. Here's an example: CMCTL> SHOW RELAY 1 Relay Information ----------------------------------------- Relay number 1 Start-up time 14-AUG-2000 11:11:11 Src (ADDRESS=(PROTOCOL=tcp)(HOST=10.11.12.13)(PORT=1269)) Dest (ADDRESS=(PROTOCOL=tcp)(HOST=10.11.12.16)(PORT=2683)) Number of IN bytes 3646 Number of IN packets 31 Number of IN DCD probes 0 Number of OUT bytes 6427 Number of OUT packets 32 Number of OUT DCD probes 0 Wow! Now we've got all sorts of useful and interesting information. I wish this information were available without having to use Connection Manager. The Src and Dest lines show you the protocol addresses involved in the connection. In this example, Src represents the TCP/IP address being used by Net8 on a client PC and the Dest address points to one of the dispatcher processes running on the server. In the case of a dedicated server connection, the Dest address will point to the server's listener process. The remaining information provides details about the amount of data being passed back and forth between client and server through Connection Manager. The Number of . . . packets refers to Net8 packets. A packet is the amount of data that Net8 transmits at one time. In this case, a total of 3,646 bytes were received from the client in 31 separate packets. | | The RELAY_STATISTICS profile parameter must be set to YES in order for Connection Manager to track the statistics showing the number of bytes and packets sent back and forth. The default setting for RELAY_STATISTICS is NO, and will result in zeros being displayed for all those statistics. | | 9.5.2.4 Examining rules If you've defined access control rules in your cman.ora file, you can view those rules using Connection Manager Control's SHOW RULES command. Here's an example: CMCTL> SHOW RULES Rule List ----------------------------------------- (RULE=(SRC=10.11.12.17)(DST=10.11.12.13)(SRV=payroll.gennick.org)(ACT=REJECT)) (RULE=(SRC=10.11.12.x)(DST=10.11.12.13)(SRV=payroll.gennick.org)(ACT=ACCEPT)) (RULE=(SRC=10.11.13.x)(DST=10.11.12.16)(SRV=hr.gennick.org)(ACT=ACCEPT)) You can also view the rules by looking in your cman.ora file, but the SHOW RULES command displays the rules that are actually being enforced by Connection Manager at any given moment. Rules are only read from cman.ora when Connection Manager starts, and if the file has been edited since then, it may not reflect the rules currently being enforced. SHOW RULES is a more reliable source of rules information and is especially useful when debugging rules-related connection problems. 9.5.3 Managing Log Files By default, Connection Manager doesn't generate any type of log file. However, you can change that behavior by setting the LOG_LEVEL attribute in the Connection Manager profile. The different log levels are described in Table 9.2 along with the profile attributes. Level 1 is a basic level that provides for the logging of significant events such as startup and shutdown. Log level 2 adds details to the log regarding access control rule enforcement. Log files are generated by both the gateway and admin processes, so when you enable logging, you're going to get two files. The naming convention used for log files is: cman_ pid .log (gateway process) cmadm_ pid .log (admin process) The pid in this case refers to the process ID. Each time you start Connection Manager, you'll get a different set of process IDs, and hence a different set of log file names . Connection Manager logs are always written to the $ORACLE_HOME /network /log directory. 9.5.3.1 Setting the log level in the profile You can set the log level in your Connection Manager profile via the LOG_LEVEL attribute. For example, the following profile establishes a log level of 1: CMAN_PROFILE = (PARAMETER_LIST = (LOG_LEVEL = 1) (RELAY_STATISTICS=yes) ) Setting the log level in the profile like this causes both processes (admin and gateway) to generate log files. In fact, it's the only way to get a log file out of the admin process. The following example shows the log entries written by the gateway process and the admin process when Connection Manager is started: [oracle@donna log]$ cat cman_1234.log (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=10)(VERSION=8.1.6.0.0) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=36)(RULE_LIST = (RULE = (SRC = 10.11.12.17) (DST = 10.11.12.13) (SRV = payroll.gennick.org) (ACT = REJECT)) (RULE = (SRC= 10.11.12.x) (DST = 10.11.12.16) (SRV = donna.gennick.org) (ACT = ACCEPT)) (RULE = (SRC = 10.11.13.x) (DST = 10.11.12.16) (SRV = hr.gennick.org) (ACT = ACCEPT))) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=32)(PARAMETER_LIST=(MAXIMUM_RELAYS=128) (RELAY_STATISTICS=yes)(AUTHENTICATION_LEVEL=0)(LOG_LEVEL=1)(SHOW_TNS_INFO=no) (ANSWER_TIMEOUT=0)(MAXIMUM_CONNECT_DATA=1024)(USE_ASYNC_CALL=yes)(TRACING=no) (TRACE_DIRECTORY=default)(MAX_FREELIST_BUFFERS=0)(REMOTE_ADMIN=no)) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=34)(address_list = (address=(protocol=tcp)(host=localhost)(port=1630))) (TIMESTAMP=14-AUG-2000 14:22:31)(EVENT=38)(COMMAND=2) [oracle@donna log]$ cat cmadm_1232.log (TIMESTAMP=14-AUG-2000 14:22:29)(EVENT=Sent Admin Status to UI) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=CMan Registration) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=Querying Names Server begins) (TIMESTAMP=14-AUG-2000 14:22:30)(EVENT=Registration/Deregistration into Names Server begins) The log for the gateway process shows the rules and profile parameter settings in effect when the process was started, and it will also show the protocol addresses on which Connection Manager is listening. The log for the admin process records the startup tasks performed when that process was started. Both logs record ongoing activity. 9.5.3.2 Using cmctl to change the log level Using Connection Manager Control's SET LOG_LEVEL command, you can change the log level dynamically while Connection Manager is running. In the following example, the log level is changed to 2 in order to cause rule list lookups to be logged: CMCTL> SET LOG_LEVEL 2 Profile of the CMAN ----------------------------------------- LOG_LEVEL = 2 The admin process generates very few log entries, so if you enable logging after you've already started Connection Manager, you may not ever see a log file generated for the admin process. 9.5.3.3 Rule list lookup logging Log level 2 enables rule list lookup logging. The process of checking new connections against the access control rules is recorded in the log file. The results from that process are recorded as well, making this log level a great debugging aid when rules aren't being enforced as you expect them to be. The following set of log entries was generated by a connection attempt that ultimately failed because it didn't meet any of the criteria specified by the access control rules. Pay special attention to the three highlighted lines containing the text (RULE=0), (RULE=1), and (RULE=2): (TIMESTAMP=14-AUG-2000 11:34:32)(EVENT=38)(COMMAND=2) (TIMESTAMP=14-AUG-2000 11:34:49)(EVENT=102)(RLYNO=0)(ADDRESS=(PROTOCOL=tcp) (HOST=10.11.12.13)(PORT=1299)) (TIMESTAMP=14-AUG-2000 11:34:49)(EVENT=106)(RULE=0)(MATCHES=0) (TIMESTAMP=14-AUG-2000 11:34:49)(EVENT=106)(RULE=1)(MATCHES=2) (TIMESTAMP=14-AUG-2000 11:34:49)(EVENT=106)(RULE=2)(MATCHES=0) (TIMESTAMP=14-AUG-2000 11:34:49)(EVENT=20)(RLYNO=0)(REASON=17)(ADDRESS= (PROTOCOL=tcp)(HOST=10.11.12.13)(PORT=1299)) The first few lines in the log file record the new connection attempt and its source. In this case, the relay number assigned to the connection was 0, and the source was port 1299 on the host with the IP address 10.11.12.13. The next three lines show Connection Manager in the process of checking the connection against the access control rules. Three rules have been defined, and they are numbered in the order in which they appear in the cman.ora file. The numbering also corresponds to the order in which they are displayed when you execute the SHOW RULES command. For example: [oracle@donna log]$ cmctl show rules CMCTL for Linux: Version 8.1.6.0.0 - Production on 14-AUG-2000 14:57:39 (c) Copyright 1998, 1999, Oracle Corporation. All rights reserved. Rule List ----------------------------------------- (RULE=(SRC=10.11.12.17)(DST=10.11.12.13)(SRV=payroll.gennick.org)(ACT=REJECT)) (RULE=(SRC=10.11.12.x)(DST=10.11.12.16)(SRV=donna.gennick.org)(ACT=ACCEPT)) (RULE=(SRC=10.11.13.x)(DST=10.11.12.16)(SRV=hr.gennick.org)(ACT=ACCEPT)) In order for a rule to be relevant, there must be a match between the connection being made and the following three rule elements: -
The source host (name or IP address) -
The destination host (name or IP address) -
The database service name As Connection Manager evaluates each rule, it writes an entry to the log file showing the rule number and the number of attributes that match. According to the log file entries just shown, none of the three rules matched on all three attributes. (RULE=1) came closest with two out of the three attributes matching. When no rules match, Connection Manager rejects the connection. The rejection isn't too obvious in the log file. The last line, containing (REASON=17), represents Connection Manager's rejection of the connection based on the rules that were defined. Whenever a new connection is attempted, Connection Manager begins to evaluate each rule in the order in which it is defined in the cman.ora file. Rule evaluation stops when a rule is found that matches the connection on all three attributes. The following example shows such a case (notice the highlighted lines). The same three rules applied this time as for the previous example, but only two were evaluated: (TIMESTAMP=14-AUG-2000 11:35:26)(EVENT=38)(COMMAND=2) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=102)(RLYNO=0)(ADDRESS=(PROTOCOL=tcp) (HOST=10.11.12.13)(PORT=1304)) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=106)(RULE=0)(MATCHES=0) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=106)(RULE=1)(MATCHES=3) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=104)(RLYNO=0)(ADDRESS=(PROTOCOL=tcp) (HOST=10.11.12.16)(PORT=1523)) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=105)(RLYNO=0)(ADDRESS=(PROTOCOL=tcp) (HOST=10.11.12.13)(PORT=1304)) (TIMESTAMP=14-AUG-2000 11:35:41)(EVENT=26)(RLYNO=0)(SRC=(ADDRESS=(PROTOCOL=tcp) (HOST=10.11.12.13)(PORT=1304)))(DST=(ADDRESS=(PROTOCOL=tcp)(HOST=10.11.12.16) (PORT=2683))) Evaluation stopped with the second rule (RULE=1) because the connection matched on all three attributes. Subsequent log entries show Connection Manager contacting the destination listener (EVENT=104), relaying a response back to the client (EVENT=105), and finally establishing the connection between the client and an MTS dispatcher (EVENT=26).  | 
