Using-scripts-in-STM

Using-scripts-in-STM


Using Scripts in STM


Scripts can be written in any language, but the preferred language is Python because of its excellent support for Rest API programming. For simple tasks, shell scripts are a good choice.

Scripts are located and placed in the file manager, under the System tab. In the Ubuntu file system, they are in /etc/stmfiles/files/scripts.

The 7.3 release contains some new features for scripts. These are indicated below with *.


The scripts can be used in the following manner:

  • to start a script when the system starts
  • to define a script to be used in conjunction with the alarms & conditions mechanisms
  • to run a script periodically according to a schedule (like cron)

Script Configuration

Scripts have the following configurable attributes.

  • file_name: the name of the script file to run. The file should normally be in the /etc/stmfiles/files/scripts directory (i.e. where they will be placed by the file manager). If no filename is given, it defaults to the name of the script object. If no file extension is given, the directory is examined for suitable files, in the order: no extension, .py, .sh.
  • directory: the directory containing the script. The default is as described above.
  • argument: a string which will be passed as a command-line argument to the script. This allows the same script to be used for different purposes (e.g. to turn something on and to turn the same thing off).
  • run_on_boot: if true, the script will run when the system starts. If false, the script will not run when the system starts, but may be scheduled, run for an alarm, or run manually.
  • persistent*: if true, the script will be restarted if it terminates (for example, because of a bug. To guard against scripts having serious errors, a script will be restarted a maximum of 100 times, and not more than once per minute.
  • start: this is an action attribute. When set to true, the script will be started.
  • stop: this is an action attribute. When set to true, the script will be stopped.
  • start_times: one or more start times, expressed as hh:mm, as explained below.
  • end_time: optional end time, as explained below.
  • interval: optional interval between runs, expressed as a duration (e.g. 1h, 10m, 1:30 for 1.5 hours), as explained below. It must not be less than one minute.
  • days: if specified, the days on which the script should run (the names of the days can be abbreviated to three letters).

Monitoring Script Activity

Scripts maintain the following attributes for monitoring their operation.

  • last_error*: the last line written to stderr by this script (or blank if none).
  • last_restart*: for a scripted marked persistent, the last time it was restarted.
  • last_run: the last time the script was run, for any reason.
  • last_status*: exit status from the last time this script ran. Should normally be 0, indicating success.
  • next_run: for a scheduled script, the next time it will be run.
  • restart_count*: for a scripted marked persistent, the number of times it has been restarted.
  • use_count: the number of times the script has been run.

Scheduling Scripts

There are several options for scheduling scripts.

  1. Periodic, at no particular time: if just interval is specified, the script will be run when the object is created, and thereafter at the specified interval.
  2. Periodic, with a definite start time: if an interval and a single start time are specified, the script will run at the given start time, and thereafter at the specified interval. For example, if the start time is 00:15, the interval is 1h (one hour) and the script is created at 11:32, the script will run for the first time at 12:15, and then every hour. The start time should be the first time in the day that the script is to be run. For example, to run on the hour, every hour, specify start time 00:00 and interval 1h.
  3. Periodic, for part of the day: if an interval, a single start time, and an end time are all specified, the script will run at the start time every day and thereafter at the specified interval until the end time is reached.
  4. At specified times: if one or more start times are given and no interval, the script will run at exactly those times.

In addition, days of the week can be specified. In this case the script will run only on the specified days of the week. Nothing else changes.

Logging*

STM creates a log file, /var/log/stm_script.log, to contain output from scripts as well as recording when they are started and stopped. This information is not placed in the normal log file. Every line written to stdout or stderr is placed in the log. This is intended primarily for debugging and trouble shooting. Scripts which need to produce output for later use should write to a designated file.

Whenever a line is written to stderr, it is also placed in the last_error attribute of the script file. This makes it easy for a failing script to leave a "last word" to help with trouble shooting.

Log files are rotated and up to 10 older versions are kept.

Scripts for Alarms

An alarm condition can specify a script to be run when an alarm is created, and for when it is cleared. The script must be an existing script object.

When an alarm is created, the script file is run with three arguments:

  • the URL of the alarm object
  • the URL of the condition object
  • the URL of the object that triggered the alarm

These can be accessed using the sys.argv object in Python, or the equivalent in other languages. They can use Rest GET requests to obtain more information about the alarm or the triggering object. It is as though the script had been run with a command line like:

/etc/stmfiles/files/scripts/host_alarm.py /rest/stm/configurations/running/alarms/42 /rest/stm/configurations/running/conditions/host_alarm /rest/stm/configurations/running/fibs/fib0/hosts/24.73.12.143

When an alarm is cleared, the script file is run with two arguments:

  • the URL of the alarm object
  • the URL of the subject of the alarm.

The auto_script Directory*

Simple scripts that do not need any parameters or scheduling information can be run simply by copying them to the auto_scripts directory under file manager. When a file is copied to this directory it will automatically be run within the following minute.

  • The file must be either begin with '#!' to indicate the language in use, or must have the extension .sh.
  • Generally, this is intended for scripts that are to run continuously. If the script stops, it will not be restarted. If it needs to be persistent, i.e. restarted if it fails, then it should be created as a script object using a file in the normal scripts directory.
  • If the file is deleted from the auto_scripts directory, the script will be stopped within a few minutes.
  • The script appears in the scripts collection, with a name based on the filename, and can be examined there. It has the attribute auto_script set to true.
  • If the scripts writes to stdout or stderr, this output will be collected in the log file as for any other script.

Examples

Run the script hourly.py once per hour, starting when the command is given:

cli# script hourly interval 1h

Run the script hourly.py at 30 minutes past every hour:

cli# script hourly interval 1h start_time 00:30

Run the script frequent.py every 10 minutes, on the hour and subsequently:

cli# script frequent interval 10m start_time 00:00

Run the script daytime.py every 30 minutes between 8.30 and 6pm:

cli# script daytime interval 30m start_time 08:30 end_time 18:00

Run the script peak_time.sh at 9am with the argument 'on' and at 5.30pm with the argument 'off':

cli# script peak_on file_name peak_time.sh argument on start_time 09:00
cli# script peak_off file_name peak_time.sh argument off start_time 17:30

Run the script eat.py at the indicated times:

cli# script eat start_time 8:00,12:30,18:00,23:15 

Run the script weekdays.py every hour during the working day:

cli# script weekdays start_time 9:00 end_time 6:00 interval 1h days monday,tuesday,wednesday,thursday,friday