next message in archive
next message in thread
previous message in archive
Index of Subjects
CSuite includes a comprehensive debugging system/strategy that has probably never been suffiently documented... ;-( Basically, every time a CSuite shell/cgi script is executed, it checks to see what level of debugging (if any) should be used. *** Elements of the CSuite Debugging System *** *********************************************** The debugging output (if any) is controlled by the set_debug_level() function included in CS_LIB/cs-shlib (1) and the associated data file... CS_CONF/debug This function is called every time a CSuite script is executed. (1) (and invoked by ./.cgi-funclib which is a symbolic link to CS_LIB/cs-shlib) *** The Debugging Data/Configuration File *** ********************************************* The data file 'CS_CONF/debug' allows a site to specify the default type of debugging... DEBUG_global ...along with setting an 'over-ride' for particular scripts. (I'll include an example of this file at the end of this message.) --- Debugging levels are: 0 - off 1 - overwrite previous debugging output 2 - append this debugging information to previous debugging information (for this script) **************************IMPORTANT************************* You should note that '-'s in a program name are specified as '_'s in the DEBUG data file. Users will get strange output if you get it wrong... **************************IMPORTANT************************* *** Location of Debug Files *** ******************************* Debugging information is either stored in: CS_LOG/DEBUG.prog_name - usually processes executed by cron /tmp/$USER/DEBUG.prog_name - processes running with the user's permissions Just to confuse things... CS_ROOT/bin/shell stashes debugging information for the last (or current) session in ~/.shell-errors *** MANAGING DEBUGGING FILES (Output) *** ***************************************** Some CSuite scripts are both large and frequently executed... should you find it necessary to use level 2 (append) debugging for a frequently executed script you should utilize some strategy/mechanism to prevent debugging files from taking over your system with potentially harmful effects to user sessions and system processes. On CCN we are usually reluctant to use debug level 2 unless we have a known problem, and then we prefer to solve the problem and return debugging to level 1 or 0. If we expect to maintain level 2 debugging for any significant period of time we add an entry in CS_ROOT/cronbin/rotate-logs to rotate the debugging files... this is similar to out management of other log files. --- In addition, as a matter of course, we delete any debug files that are left lying around and that haven't been accessed in a week. ----- HERE AT CCN ----- ----------------------- We have global debuging set to 1 (overwrite) DEBUG_global=1 ----- We have a few scripts that we are currently keeping a minimum of several day worth of debuging information. Currently we have the following entries in CS_CONF/debug to force level 2 debuging... DEBUG_memfind=2 DEBUG_memupdate=2 DEBUG_cs_sudo=2 DEBUG_mk3=2 DEBUG_domkip=2 DEBUG_mkmdml=2 DEBUG_mdml_create=2 DEBUG_chk_grlist=2 DEBUG_namedbupdate=2 DEBUG_csuite_cron=2 DEBUG_passwd_edit=2 ************************* REMEMBER ************************* The character '-' in a program name is specified as '_' in the DEBUG data file. Users will get strange output if you get it wrong... ************************* REMEMBER ************************* ...and, we have a few scripts for which we are currently maintaining no debuging information: DEBUG_update=0 DEBUG_mail=0 DEBUG_tq=0 DEBUG_last=0 DEBUG_adjblackout=0 DEBUG_cs_quota=0 DEBUG_makelynxip=0 DEBUG_userclass=0 DEBUG_clear=0 DEBUG_dirmatch=0 DEBUG_shell=0 DEBUG_quota_view=0 DEBUG_safe_rm=0 DEBUG_putdate=0 DEBUG_clear=0 DEBUG_lock=0 DEBUG_unlock=0 DEBUG_mail_forward=0 DEBUG_login2dir=0 DEBUG_lpansi=0 ***** General Debugging Strategies ***** **************************************** If you are experiencing problems and want to capture some debugging information... 1) start by making sure global debugging is set to '1' ...as we have in the example above. 2) set the debugging level of scrips involved in this to level '2' Scripts in CS_ROOT/cronbin are usually a good place to start... If the problem is with the ip creation process start by setting level '2' for: CS_ROOT/cronbin/ipmaint (and the files it calls) CS_LIB/mk-ipjumpfile CS_LIB/domkip note: the actual path for CS_LIB, CS_LOG, and CS_CONF should be specified in CS_ROOT/etc/conf/vars 3) collect some data... create a couple of test ip's or whatever you need to do to 'exercise' the routines that you think are failing. 4) have a look in the CS_LOG/DEBUG.* files. If you've got global debugging set to 1 there should be quite a few DEBUG.* files. If you're nor sure what files to look in first... you might want to `grep "error" DEBUG.* ` and see what jumps out at you. 5) If you find a script that's failing, have a look at the error message. Often the error will suggest that either a) the script is encountering a 'permission' problem, or... b) that a script is expecting a value in an environmental variable that has not been set. 6) If you find an error in debugging output that you can't figure out... send us a copy of the debugging output. It's better to send it directly to an individual than to the list which goes to many people. comments welcome david potter
next message in archive
next message in thread
previous message in archive
Index of Subjects