rc.listener - General purpose maintenance utilities for Oracle listener, System V (Solaris, AIX, Linux) start/stop scripts, and VCS Sqlnet agents.
rc.listener lsnr=LNSR action=start flag=Y|N|NO_CHANGE|NC (Default Y) verbose=Y|N (Default N)
rc.listener lsnr=LNSR action=stop flag=Y|N|NO_CHANGE|NC (Default N) method=immediate|abort (Default immediate) verbose=Y|N (Default N)
rc.listener lsnr=LNSR:psonly|nomonitor action=status|stat flag=Y|N (Default No flag check) verbose=Y|N (Default N)
rc.listener lsnr=LNSR action=restart verbose=Y|N (Default N)
rc.listener lsnr=LNSR action=reload verbose=Y|N (Default N)
rc.listener lsnr=LNSR action=flag flag=Y|N verbose=Y|N (Default N)
S|Knumberlistener start|stop|restart|reload|status|stat
S|Knumberlistener-LNSR start|stop|restart|reload|status|stat
S|Knumberoracle-LNSR start|stop|restart|reload|status|stat (Depreciated)
online LNSR[:psonly|nomonitor]
online . . . . LNSR[:psonly|nomonitor]
offline LNSR[:psonly|nomonitor]
offline . . . . LNSR[:psonly|nomonitor]
clean LNSR[:psonly|nomonitor]
clean . 0|1|2|3|4 . . . LNSR[:psonly|nomonitor]
monitor LNSR[:psonly|nomonitor]
monitor . . . . LNSR[:psonly|nomonitor]
* help=y
* version=y
rc.listener is a single shell program to start, stop, test Sqlnet listener; check and update the flag; and send notifications, if configured, for abnormal listener conditions, and when the N flag becomes too old.
rc.listener is 3-in-1, multifunctional program serving different purposes when installed with different names. When named rc.listener, its canonical name, it is a general purpose program; when linked as S|Knumberlistener or S|Knumberlistener-LNSR, it is used as System V start / stop script; when linked as online, offline, clean, and monitor, it is VCS (Veritas Cluster Server) Sqlnet agent.
Before we describe each of 3 functionalities, we need to define the oratab entries for listener.
Oracle does not define oratab entries for listener. We use two ways to handle this: (1) each Sid has its own listener named LISTENER_Sid; or (2) use a commented out entry in the format:
##_<listener_name>:oracle_home:Y
Use one or the other, do not mix them. For example, if one non-standard listener name needs to be listed as above, list all listeners even for standard listener names. Otherwise rc.listener do not know how many listeners you have, and what their names are.
Please see this section in rc.oracle help=y for relocation of oratab for systems which put oratab on /etc.
Please see this section in rc.oracle help=y for discussion of oracle database flag. We confer the same semantics on listener flag.
The VCS agent uses the flag to determine whether to monitor the listener or not. If you shutdown the listener for maintenance, you should change the flag to N so that the agent won't start it up. Change the flag to Y if you want to the agent to monitor it.
rc.listener combines the two steps - listener start/stop and flag change - for you.
When used as a general purpose utility for most common use, you specify two parameters, the listener you are operate on, and the action which is either start, stop, restart, reload, status, flag (show or change flag. The verbose=y option allows you the lsnrctl output.
For the START action, the default behavior is to startup the listener, and change the flag to Y. However you can specify the flag to be either Y or N, or NO_CHANGE.
For the STOP action, the default behavior is to shutdown the listener and change the flag to N. Again you can specify the flag to be either Y or N, or NO_CHANGE.
The method option lets you specify how you want to shutdown. The default is IMMEDIATE, which uses lsnrctl stop command to shutdown the listener. The ABORT method kills the listener process.
The FLAG action shows you the current flag, or change it to what you asked for.
The STATUS or STAT action checks the health of the listener. If the FLAG option is Y, it checks the flag for the listener in oratab and only test the listener when the flag is Y.
The rc.listener utility can used manually, or embedded in other programs.
When the program is named as S|Knumberlistener-LSNR, or S|Knumberlistener, it can be used as system V start/stop scripts. The former is to start/stop the particular listener regardless the flag. The latter is to start/stop ALL listeners whoes flag is Y.
For example:
To start / stop listeners with Y flag on Solaris:
cp rc.listener /etc/init.d/rc.listener ln /etc/init.d/rc.listener /etc/rc2.d/S90listener ln /etc/init.d/rc.listener /etc/rc0.d/K10listener
The location and naming conventions are slightly different on other Sys V derived systems:
On AIX 5.2:
cp rc.listener /etc/rc.d/init.d/rc.listener ln /etc/rc.d/init.d/rc.listener /etc/rc.d/rc2.d/S90listener ln /etc/rc.d/init.d/rc.listener /etc/rc.d/rc2.d/K10listener
On SuSE Linux (2.4.7):
cp rc.listener /etc/init.d/rc.listener ln /etc/init.d/rc.listener /etc/init.d/rc3.d/S90listener ln /etc/init.d/rc.listener /etc/init.d/rc3.d/K90listener
rc.listener supports chkconfig. On redhat based systems, you can use chkconfig to add and delete the service:
# chkconfig --add rc.listener # chkconfig --list rc.listener rc.listener 0:off 1:off 2:on 3:on 4:on 5:on 6:off # chkconfig --del rc.listener
When the program is named online, offline, clean, and monitor, it can be used as VCS (Veritas Cluster Server) Sqlnet agent.
This is done by installing the Solaris package MERotas provided in rc.listener distribution. The following procedure is for illustration purpose only.
#* For illustration purpose only, please use package for your platform. *#
mkdir -p /opt/VRTSvcs/bin/Sqlnet
cp rc.listener /opt/VRTSvcs/bin/Sqlnet/rc.listener
cd /opt/VRTSvcs/bin/Sqlnet
for i in online offline clean monitor; do
ln rc.listener $i
done
ln -s ../ScriptAgent SqlnetAgent # VCS provided
Please also see add_sqlnet_to_vcs.ksh in the distribution on how to add the service to VCS. Lsnr is the sole parameter that needs to register in VCS. Basically,
online LSNR = rc.listener lsnr=<LSNR> action=start flag=Y offline LSNR = rc.listener lsnr=<LSNR> action=stop method=immediate flag=Y clean LSNR = rc.listener lsnr=<LSNR> action=stop method=abort flag=Y monitor LSNR = rc.listener lsnr=<LSNR> action=stat flag=Y
We can run the commands on the left side manually before testing VCS.
The extended Lsnr can be used in the format LSNR:psonly|nomonitor. The qualifiers psonly and nomonitor, which are case inSENsiTIVE, are only applicable how the Lsnr is tested.
psonly, as the name suggests, is used to test only the existence of listener process. The presence of the process does not mean the listener is working properly.
nomonitor, as the name suggests, is used not to test the the listener, but considers it to be up.
These two qualifiers are used mainly for VCS, to prevent it from automatically restart the listener. It does not affect the failover.
A monitor program should be in place when used these two qualifiers.
ZERO configuration is required for normal use of rc.listener.
However, following the philosophy of ``simple things should be easy but complicated things should be possible'', the configuration file in:
$ORACLE_BASE/.ora_${LSNR}_env.ksh or
$ORACLE_BASE/.ora_${SID}_env.ksh
can be used for these parameters:
MAILLIST PAGELIST FTIME
The format of specification is ``key = value''. The left side should contains the key, and optionally white spaces and other characters; the right side should contain the value and possibly white spaces. The key is case INsenSItive.
So the following format all valid, and equivalent:
# MailList = dba_list@foo.com MAILlist=dba_list@foo.com
MAILLIST and PAGELIST are used for VCS agent notification. The agent sends page to PAGELIST when (a) monitor failed; (b) monitor produced an unexpected status; (c) listener start and stop. Unfortunately, monitor can not send page when the it times out. But hopefully, the notification will be sent by clean and online. The agent sends mail to MAILLIST when the N flag for the database becomes too old (older than FTIME if set, or 1 day).
The FTIME is a number in minutes, which provides a way for you to tell rc.listener that you the flag is changed to N for x minutes. rc.listener will send email to MAILLIST if this limit is exceeded, once per day between 08:00 and 08:15 hours.
The VCS monitor spits the following informational messages which can be used for log monitor. The ``110'' and ``100'' are return code required by VCS. They are not part of the message.
110 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was up. 110 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] needed attention. Details in <logdir>. 110 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was not tested with recent N flag. 110 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was not tested with old N flag. 110 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] had unexpected status. Details in <logdir>. 100 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was down. Details in <logdir>.
The return codes for system V start / stop script are not used. The brief message informs the SA what is going on:
YYYY-MM-DD HH24:MI:SS Running S|K<number>listener with start|stop option. This may take a few minutes. When in doubt, please check <logdir>. Working on <Lsnr> ... YYYY-MM-DD HH24:MI:SS <Lsnr> was up|down.
The return codes for start/stop should not be trusted. Either check the specific messages produced by lsnrctl, or follow up start/stop with stat. The return code and informational messages for rc.listener status option are:
0 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was up. 1 YYYY-MM-DD HH24:MI:SS <LSNR>[:psonly|nomonitor] was down. !0 YYYY-MM-DD HH24:MI:SS <other messages.>
For example, you can say:
rc.listener lsnr=<LSNR> action=stat || print "<LSNR> did not come up."
For flag change, it is better to check directly, for example:
[[ $(rc.listener lsnr=<LSNR> action=flag) == "Y" ]] || exit 1
Please see this section in rc.oracle help=y.
Please see this section in rc.oracle help=y.
Michael Wang <xw73@columbia.edu> with help from many people. Contributions are acknowledged in the version history within the programs.
version 10.6, 2008-05-26, Michael Wang <xw73@columbia.edu>. * Port to ksh 88 requested and sponsored by + DataBase Intelligence Group (http://dbigusa.com). * Various fix and clean up.
version 10.5, 2004-10-18, Michael Wang <xw73@columbia.edu>. * Enhanced get_var function.
version 10.4, 2004-08-29, Michael Wang <xw73@columbia.edu>. * Tested on standalone AIX 5.2 with reboot.
version 10.3, 2004-08-23, Michael Wang <xw73@columbia.edu>. * revert to changing flag to Y after online|offline|clean + per discovery of VCS behavior by Jose Bacalla. * Added flat_opt function.
version 10.2, 2004-08-21, Michael Wang <xw73@columbia.edu>. * Tested Linux RAC (Oracle 9.2.0.4 on RHEL 3.0 compatible).
version 10.1, 2004-08-20, Michael Wang <xw73@columbia.edu>. * Tested on AIX 5.2 VCS with Roy Morton.
version 10.0, 2004-08-10, Michael Wang <xw73@columbia.edu>. * Rewrite to address the following issues: + PSONLY and NOMONITOR options. + Optional notification for monitor failure and state change. + Self maintained logs: clean user experience and capability to debug. + Linux (redhat) support: chkconfig and subsys lock. + modularity attempt for futher development: rc_listener function.
version 9.6, 2003-06-10, Michael Wang <xw73@columbia.edu>. * Handles LISTENER_<SiD>, listener_<SiD>, and LisTNer_<Sid>.
version 9.5, 2003-03-04, Michael Wang <xw73@columbia.edu>. * Changed "ksh $0" to "$0" so that what in #! line will be used. * Set UNIX95 for HP-UX to get SUSv2 bahavior for ps command (-o option).
version 9.3b, 2002-11-20, Michael Wang <xw73@columbia.edu>. * Added "[[ -n "$PID" ]]" before "kill $PID".
version 9.3a, 2002-10-01, Michael Wang <xw73@columbia.edu>. * Fixed the typo "RANDOWM => RANDOM".
version 9.3, 2002-04-25, Michael Wang <xw73@columbia.edu>. * Added version=y. * "kill -KILL $i" => "kill -KILL $PID".
version 9.2, 2002-01-14, Michael Wang <xw73@columbia.edu>. * Accepts both LISTENER_SID and SID_LISTENER as site standard. * Fixed the problem that "help=y" leaves an empty dir in /tmp. * Added the missing 2nd "$" in "cp -p $ORATAB $ORATAB.tmp". * Changed "exit -- $?" to "exit $?": (exit -- 1); print $? => 0 in ksh88.
version 9.1, 2001-12-03, Michael Wang (xw73@columbia.edu).
* New way of getting SID_LINE:
(1) SID_LISTENER => $ORACLE_BASE/.rc.oracle.cf: ##_<LISTENER_NAME>:*
(2) LISTENER_NAME => $ORACLE_BASE/.rc.oracle.cf: ##_<LISTENER_NAME>:*
(3) /var/opt/oracle/oratab: ##_<LISTENER_NAME>
(4) /var/opt/oracle/oratab: SID:*
* Derive owner from $ORACLE_HOME/bin/lsnrctl.
* TNS_ADMIN default to $ORACLE_HOME/network/admin or /var/opt/oracle
wherever listener.ora exists.
* Added reload option.
* Fix FTIME issue:
j=; unset j; j=011; print "$j" => 9
typeset -Z6 j; j=; print "$j" => "<sp><sp><sp><sp><sp><sp>"
- Bourne shell detection simplification. "PATH= print" and (print) forks,
and only forked stderr can be redirected in Bourne shell.
- Changed "exit -- -1" to "exit 127". (exit -- -1); print $? => 0 in ksh88.
version 9.0, 05/26/2001, Michael Wang (xw73@columbia.edu).
* Added "METHOD=abort" for stop option, which is used by VCS clean, per
Mike Suarez. This fixes problem preventing failover when network is down.
* Added "ps" test in monitor to prevent hanging when network is down.
* Added support for locally installed Oracle software ("VCS Concurrency
Violation") per Alfonso Di Capo, Andrew Blatt, Babar Saeed, Diane Yee.
* Added pager/email notification, and action=page|mail, message=... options
with help from Andrew Blatt, Janet Zhu on CVS. "A nasty solution for a
nasty problem in a nasty world"(TM).
* Check FLAG before lsnrctl to ease the upgrade per Raj Pande.
* "help=y" now uses "real man"(TM) page. Eliminated less helpful online help.
* FLAG/FTIME update fix.
- used POSIX PATH.
- Use of POSIX "id -u" and "id -un" command.
- Added "print" in additon to "$RANDOM" for ksh test to exclude bash.
- Fixed "... | SUCCESS=Y". In PD KSH v5.2.14 99/07/13.2 (on Red Hat Linux
7.1, Kernel 2.4.4), the last pipeline is not run in current shell.
- Changed "exit -1" to "exit 127" for PD KSH.
- Workaround different behaviors on "Ctrl-C" on trap between PD KSH and
AT&T KSH: PD KSH does not run exit trap upon "Ctrl-C", AT&T KSH does.
- uses cp -p $ORATAB $ORATAB.tmp to create a temp file with same permission.
- Eliminate fork (grep) in processing SID_LINE.
version 5.4, 02/21/2001, Michael Wang (xw73@columbia.edu).
* Tightened up the locking code.
* Added restart option for convenience only per Raj Pande. It stop and start
the listener with default options.
* Added identifier "$LISTENER: " for flag change message.
* exit 255 => exit -1
* Change [[ -z $ORATAB && -r $i ]] && ORATAB=$i to
[[ -r $i ]] && { ORATAB=$i; break; }
* Last line of start/stop options was: [[ $SHOW = Y ]] && exit -1.
[[ $SHOW = Y ]] would be the last command if it is false and hence its
status becomes the status of the script. The last line is changed to:
(( status == 0 && fstatus == 0 )).
version 5.3, 01/31/2001, Michael Wang (xw73@columbia.edu).
* Added date before "tail -1".
* Change [[ -z $Perl && -x $i ]] && Perl=$i to
[[ -x $i ]] && { Perl=$i; break; } for efficiency.
version 5.2, 01/26/2001, Michael Wang (xw73@columbia.edu). * Added ftime= option for start/stop.
version 5.1, 01/05/2000, Michael Wang (xw73@columbia.edu). * change "exit 0" to "exit $?" in oracle-SID case. This affects backup. * change "FOREVER" to "1 DAY".
version 5.0, 12/25/2000, Michael Wang (xw73@columbia.edu). To keep in sync with rc.oracle
version 4.0, 10/10/2000, Michael Wang (xw73@columbia.edu).
* version number advanced beyond pi.
* Exit code changed from 0 to 4 when Oracle executable can not be found.
* Array can not be reset on Version M-11/16/88f on AIX 4.3.3
i[0]=; typeset -u i; i=; unset i; i=b; echo $i => B
Changed to i to ix to avoid conflict.
* "==" in [[ string == pattern ]] is replaced by "=" for compatibility
with older Korn Shell (eg Version M-11/16/88f).
* Get rid of the_space_holder.
* Unset name for name=value pair. Example, TEST=.
version 3.14159, 08/18/2000, Michael Wang (xw73@columbia.edu).
* Rewrite "[[ -z $(eval echo \$$i) ]]" as "eval [[ -z \$$i ]]".
This reduces the number of forks. This was suggested by
Dan A. Mercer on the internet.
* Prerequisite:
- /var/opt/oracle/listener.LISTENER_NAME:
LISTENER_NAME:ORACLE_HOME:Y/N:TNS_ADMIN:OWNER
version 3.1415, 07/22/2000, Michael Wang (xw73@columbia.edu).
* Expanded listener's oratab to include owner in support of running as
different $OWNER.
* Enhanced SHOW=Y option to display statement to lsnrctl.
* FLAG=NULL option for start/stop to leave FLAG alone.
* unset LD_LIBRARY_PATH.
Properly linked oracle executables do not need LD_LIBRARY_PATH.
In Oracle 8i, set LD_LIBRARY_PATH causes listener problem, Ref:
TAR 12953862.600, Doc ID 1023333.1, Bug ID 1147434.
* MASSIVE code clean up to support above functionalities and for
programming purity and efficiency.
version 3.141, 07/09/2000, Michael Wang (xw73@columbia.edu). * Minor change on PATH and id for Linux compatibility.
version 3.14, 03/17/2000, Michael Wang (xw73@columbia.edu). * implemented TNS_ADMIN.
version 3.1, 01/20/2000, Michael Wang (xw73@columbia.edu). * Minor midifications in Oracle env variable determination and verification.
version 3.0, 12/27/1999, Michael Wang (xw73@columbia.edu). * Modified in sync with oracle-SID
version 1.0, 07/29/1998, Michael Wang (xw73@columbia.edu). * IPO.