Using SADMIN Python script template

13 minute read

Posted 2021-03-16 - Updated 2021-05-05

Supported on Linux, Aix, MacOS

What you need to know to use the SADMIN tools library

The Python script template ($SADMIN/bin/sadm_template.py) is ready to use and it include everything to use the SADMIN python library. Run the template and take a look at the code.
As an example, we will create create a new script from that template and show you what are the benefits of using it.

Another ‘Hello World’ example

First, make a copy of the template Python script, into the user ($SADMIN/usr/bin) directory.

$ cp $SADMIN/bin/sadm_template.py $SADMIN/usr/bin/helloWorld.py

You should never modify the original template, always make a copy and then use the copy. The Python template supplied with SADMIN, could get updated by a newer version of SADMIN. The user directory ($SADMIN/usr) is your directory and will never be updated by future version.

With the editor of your choice, add the line below in the function called ‘main_process()’.
st.writelog ("Hello World")

One of the function included in the SADMIN Python module is “st.writelog()”. By default, it write the string it received to the screen and to the script log. If you want to write the message to the log only, you can modify the variable “st.log_type”.
st.log_type = 'B' # Output goes to [S]creen [L]ogFile [B]oth

Let’s run our script now and see the output we get.

We can divide the output of the screen in three section. We have the Header, the script execution output and finally the script Footer. Let’s explore each of these sections.

The Script Header

The script header is part of the ‘st.start()’ function included in the SADMIN module. It’s function is to initialize the script log, generate the script header (if needed), create or update the Result Code History file (.rch) and some attributes settings. After executing the ‘st.start()’ function, the SADMIN tools are ready to use.
The script header is generated by default when the call to the ‘st.start()’ function included in SADMIN Python module.
- Unless you set the attribute ‘st.log_header’ to ‘False’ in the SADMIN Section, the script header will be generated.
  st.log_header = True # Show/Generate Header in script log (.log)
The second line of the header show the script name, version number and the SADMIN module version.
- You set your script version number in the SADMIN Section of the script.
  st.ver = "2.1" # Current Script Version
- The version of the SADMIN Python module is available as a read only attribute called “st.libver”.
The third one, show the fully qualified system name (FQDN) and the system type (LINUX,AIX,DARWIN)
The fourth line show the distribution name, it’s version number and code name.
The last line is a separator line that signal the end of the header and the beginning of the script output.

By default, every script using SADMIN library will show the script footer.
- The footer is generated, unless you set the attribute ‘st.log_footer’ to ‘False’ in the SADMIN Section of the script.
  st.log_footer = True # Show/Generate Footer in script log
The first line of the footer is a separator line that signal the end of the script and the beginning of the footer.
The second line show the exit code of the script (0=Success 1=Error).
The third one, show the execution elapse time (HH:MM:SS).
Next we have the name of the [R]eturn [C]ode [H]istory file and the maximum of lines to keep in it.
- The default maximum number of lines to keep in a RCH file is taken from the SADMIN configuration file ($SADMIN/cfg/sadmin.cfg).
  SADM_MAX_RCHLINE=125
- You can override this value in your script, by changing the value of the attribute shown below.
  st.cfg_max_rchline = 125 # When Script End Trim rch file to 125 Lines
The next line inform you if a notification (alert) will be send or not.
The log file name is one the next line along with the maximum of lines to keep in it.
- The default maximum number of lines to keep in the log file is taken from the SADMIN configuration file ($SADMIN/cfg/sadmin.cfg).
  SADM_MAX_LOGLINE=2000
- You can override this value in your script by changing the value of the attribute shown below.
  st.cfg_max_logline = 1000 # When Script End Trim log file to 1000 Lines
The last two lines indicate the execution ending date and time and a line consisting of eighty equal sign ‘=’.

The [R]esult [C]ode [H]istory (.rch) file

The History (*.rch) file format

The Result Code History file, is a simple text file that is automatically created by the SADMIN Tools at the end of the execution of a script. It is use to record some information and statistics at the end of each script. Included in this file, is the date and time the script was started, when it ended and did it finish with success or failure. With this file we can also determine if a notification should be sent, who to send it and how to send it with the use of the alert group included on the line. Below is an example of what a RCH file look like.

$ cat $SADMIN/dat/rch/holmes_sadm_template.rch
holmes 2021.04.05 13:32:18 2021.04.05 13:32:22 00:00:04 sadm_template default 1 0
$ 

System	Start Date	Start Time	End Date	End Time	Elapse	Script Name	Alert Group	Alert Type	Status
holmes	2021.04.05	13:32:18	2021.04.05	13:32:22	00:00:04	sadm_template	default	1	0

First we have the host name where the script was executed, then the date and time it started and finished, followed by the elapse execution time of the script. The seventh field is the script name (without extension) and then the alert group that the notification (alert) would be sent.

The alert type is the ninth field, it dictate the action to do base on the success or failure of the script.
‘0’ mean never send an alert, whether the script was a success or not.
‘1’ mean if the script terminated with an error, send an alert.
‘2’ mean if the script terminated with success, send an alert.
‘3’ mean always send an alert whether the script was a success or not.

The last column indicate the script termination status, ‘0’ mean success and a ‘1’ a failure. It is important to know, that when a script fail it will always appear as failed in the SADMIN Web Monitor page as failed. It will stay on the monitor page until it run again and terminate with success or that you edit the ‘RCH’ file on the system that generated the error and remove the error line or change the last column from ‘1’ to ‘0’.

Do I want to use RCH file or not

By default, every time you execute a script that’s using the SADMIN Tools, there will be a line is added to the history file. If the file doesn’t exist it will be created. If the script failed, normally you get a notification (alert) by email, by SMS or by Slack. There are time when you don’t want to be alerted whatever the result of a script is. For example, if you created an interactive script you may not care about the exit code, you can then disable usage of the RCH file.
Within the shell script you can set variable ‘SADM_USE_RCH’ to ‘N’ in the SADMIN definition section of the script.

export SADM_USE_RCH="N"  # Generate or not Entry in Result Code History file`  

Within a Python script set attribute ‘st.use_rch’ to ‘False’ in the SADMIN definition section of the script.

st.use_rch = False             # Generate entry in Result Code History (.rch)

The History file name convention

The history file name (.rch) is prefix by the hostname, an underscore and followed by the script name and have an extension of ‘.rch’. Let’s assume we are on a host named ‘holmes’ and the script name is ‘helloWorld’, so the history file name will be ‘holmes_helloWorld.rch’. The RCH file are created in the SADMIN data directory ‘$SADMIN/dat/rch’.

RCH files automatically transferred to SADMIN Server

The SADMIN server collect every history files created or modified on every clients at regular interval (every 5min via a cron job in /etc/cron.d/sadm_server). It is one of the responsibility of script ‘sadm_fetch_clients.sh’ to transfer any history changed to the SADMIN server. Information included in this file will be visible from the Web interface and from the command line on the SADMIN server. It is also be used to trigger an alert, if you requested it.

Controlling the history file size

Depending how frequently you run a particular script you may want to control the size of the history file. If you run a script on a daily basis and you want to keep one month of history, then you may want to keep around 31 linus in the ‘RCH’ file. To same some disk space and to keep transfer time to a minimum, you can control the number of lines you want to keep in each history file. The default maximum number of lines to keep in the ‘.rch’ file is 35 lines and it’s taken from the SADMIN configuration file ($SADMIN/cfg/sadmin.cfg).

SADM_MAX_RCHLINE=35

You can override this default by setting the maximum number of line to trim directly in your script by changing the associated variable.

In a Shell script you change the value of the variable ‘SADM_MAX_RCLINE’

`export SADM_MAX_RCLINE=31     # When Script End Trim rch file to 31 lines   

In a Python script you change the value of the ‘st.cfg_max_rchline’ attribute.

st.cfg_max_rchline  = 31       # When Script End Trim rch file to 31 Lines

Preventing the history from being trim in a Shell script, can be done by setting the value of the variable ‘SADM_MAX_RCLINE’ to ‘0’.

export SADM_MAX_RCLINE=0   # Don't trim the history file (.rch) 

Preventing the history from being trim in a Python script, can be done by changing the value of the ‘st.cfg_max_rchline’ attribute to ‘0’.

st.cfg_max_rchline  = 0    # Don't trim the history file (.rch) 

[R]esult [C]ode [H]istory File Summary

A log file was created

Every time a script run that’s using the SADMIN Tools, there’s a log file created or updated.
Log are created in the $SADMIN/log directory.
The log file name is prefix by the host name, followed by the script name and ‘.log’ extension.
- In our example, we are on a host named ‘imac’, the script name is ‘helloWorld’, so the log name is ‘imac_helloWorld.log’.
The SADMIN server collect every updated log files from every SADMIN client every 5 minutes (via a rsync in sadm_fetch_clients.sh).
A script log can be cumulative or a new one can be created at each execution. The default in the template is set to create a new log file at each execution.
If you want your script log to be cumulative, then set ‘st.log.append = True’.
st.log_append = False # Append Existing Log
At the end of each execution, the log file is trim to the number of line specified in $SADMIN/cfg/sadmin.cfg by the variable ‘SADM_MAX_LOGLINE’.
- You can override this default by changing ‘st.cfg_max_logline’ attribute value in the SADMIN definition section of your script.
  st.cfg_max_logline = 1000 # When Script End Trim log file to 1000 Lines

Example of the log file

Log and RCH file viewed from the Web interface

Web view of our helloWorld script

Example of viewing a RCH file from the web interface

Example of a script log from the web interface

Viewing all your servers scripts results on the terminal
This option is only available on the SADMIN server.

Suppressing the script Header and Footer

To suppress header/footer from log and screen, change “st.log_footer” and “st.log_header” attribute to ‘False’.

We can see now the header and footer doesn’t appear anymore on the screen and in the log of the script.

Create a script from scratch that use SADMIN Tools

To create a Python script using the SADMIN tools you need to include these requirements in your code :

The ‘setup_admin()’ function should appear at the beginning of your script, as in the template $SADMIN/bin/sadm_template.py.

# -----------------------------------------------------------------------------
# SADMIN section - Setup for Global Variables and import SADMIN Python module
# -----------------------------------------------------------------------------
def setup_sadmin():

  # Load SADMIN Standard Python Library Module ($SADMIN/lib/sadmlib_std.py).
  try :
      SADM = os.environ.get('SADMIN')                      # Getting SADMIN Root Dir.
      sys.path.insert(0,os.path.join(SADM,'lib'))          # Add SADMIN to sys.path
      import sadmlib_std as sadm                           # Import SADMIN Python Libr.
  except ImportError as e:                                 # If Error importing SADMIN 
      print ("Error Importing SADMIN Module: %s " % e)     # Advise User of Error
      sys.exit(1)                                          # Go Back to O/S with Error
  
  st = sadm.sadmtools()                                    # Create SADMIN instance             

  # You can use variable below BUT DON'T CHANGE THEM - They are used by SADMIN Module.
  st.pn               = os.path.basename(sys.argv[0])      # Script name with extension
  st.inst             = os.path.basename(sys.argv[0]).split('.')[0] # Name without Ext
  st.tpid             = str(os.getpid())                   # Get Current Process ID.
  st.exit_code        = 0                                  # Script Exit Code (Use it)
  st.hostname         = socket.gethostname().split('.')[0] # Get current hostname

  # CHANGE THESE VARIABLES TO YOUR NEEDS - They influence execution of SADMIN Module.
  st.ver              = "2.1"        # Current Script Version
  st.log_type         = 'B'          # Output goes to [S]creen to [L]ogFile or [B]oth
  st.log_append       = False        # Append Existing Log(True) or Create New One(False)
  st.log_header       = True         # Show/Generate Header in script log (.log)
  st.log_footer       = True         # Show/Generate Footer in script log (.log)
  st.multiple_exec    = "N"          # Allow running multiple copy at same time ?
  st.use_rch          = True         # Generate entry in Result Code History (.rch) 
  st.debug            = 0            # Increase Verbose from 0 to 9 
  st.usedb            = True         # Open/Use Database(True) or Don't Need DB(False)
  st.dbsilent         = False        # When DB Error, False=ShowErrMsg and True=NoErrMsg 
                                     # But Error Code always returned (0=ok else error)

  # Override Default define in $SADMIN/cfg/sadmin.cfg
  #st.cfg_alert_type   = 1           # 0=NoMail 1=OnlyOnError 2=OnlyOnSuccess 3=Allways
  #st.cfg_alert_group  = "default"   # Valid Alert Group are defined in alert_group.cfg
  #st.cfg_mail_addr    = ""          # This Override Default Email Address in sadmin.cfg
  #st.cfg_cie_name     = ""          # This Override Company Name specify in sadmin.cfg
  #st.cfg_max_logline  = 500         # When Script End Trim log file to 500 Lines
  #st.cfg_max_rchline  = 35          # When Script End Trim rch file to 35 Lines
  #st.ssh_cmd = "%s -qnp %s " % (st.ssh,st.cfg_ssh_port) # SSH Command to Access Server 

 # Start SADMIN Tools - Initialize 
  st.start()                         # Init. SADMIN Env. (Create dir.,Log,RCH, Open DB..)
  return(st)                         # Return Instance Object To Caller

It create an instance of the sadmtools() class under the name ‘st’ ([S]admin [T]ools).

st = setup_sadmin()                         # Setup Var. & Load SADM Lib

The setup_admin() function also call the SADMIN ‘sadm_start()’ module/function, to initialize the environment.

# Start SADMIN Tools - Initialize 
st.start()                                  # Create dir. if needed, Open Log, Update RCH file..
return(st)                                  # Return Instance Obj. To Caller

Summary of what is done by the ‘st.start()’ function

Verification and creation of the SADMIN directory structure.
It create or append the script log (Depending on value you put in variable ‘st.log_append = True’).
The starting date and time is written to the Result Code History file (See ‘st.use_rch = True’).
Create the PID file, if only one copy of your script should run simultaneously (‘st.multiple_exec = “N”’).
The script header is written to the log by default (see ‘st.log_header = True’).
It create 3 unique temporaries files that are available to your script (st.tmp_file1, st.tmp_file2, st.tmp_file3).

You may want to modify some of the fields before the call is made to the start function (st.start()).

You may want to change the version number of your script (‘st.ver’).
Do you want a single copy of your script running at the same time (‘st.multiple_exec’) ?
If you plan to use the server database, ensure that the field ‘st.usedb’ is set to True (Available only on SADMIN server)
If you use the server Database, the ‘st.dbsilent’ field control what happen when an error occur :
- Either set to ‘False’ or ‘True’, when an error occur the error number will be returned to caller.
- Additionally, if ‘st.silent’ is set to False, an error message will be shown (No message when set to ‘True’).

Summary of what is done by the ‘st.stop()’ function

The ‘st.stop(st.exit_code)’ function need to be called at the end of the script (See example below).
If the server database was used (st.usedb=True), the connection to server database will be closed.

Share on

Twitter Facebook LinkedIn