samhain may invoke external programs or scripts in order to implement logging capabilities that are not supported by samhain itself (e.g. pager support). This section provides an overview of this capability.
External programs/scripts invoked for logging will receive the formatted log message on stdin. The program should expect that stdout and stderr are closed, and that the working directory is the root directory.
Each external program must be defined in the configuration file, in a section starting with the header [External] . In addition, ExternalSeverity must be set to an appropriate threshold in the section [Log] .
Each program definition starts with the line
        OpenCommand=
        /full/path 
      
Options for the program may follow. The definition of
      an external program is ended (a) when explicitely terminated
      with the line 
      CloseCommand , (b) when the
      section ends, or (c) when another 
      OpenCommand=
      /full/path line for the
      next command is encountered.
| ![[Note]](stylesheet-images/note.png) | Environment variables | 
|---|---|
| By default, the environment is limited to the TZ
        (timezone) variable. If you need other variables (e.g.
        LD_LIBRARY_PATH), you can set them using the 
        Setenviron=
         | 
There are several places in samhain where external programs may be called. Each such place is identified by a type. Currently, valid types are:
log— An external logging facility, which is handled like other logging facilities. The program will receive the logged message on stdin, followed by a newline, followed by the string [EOF] and another newline.
srv— Executed by the server, whenever the status of a client, as displayed in the HTML status table, has changed. The program will receive the client hostname, the timestamp, and the new status, followed by a newline, followed by [EOF] and another newline.
Any number of external programs may be defined in
            the configuration file. Each external program has a 
            type, which is 
            log by default. Whenever external
            programs are called, all programs of the appropriate 
            type are executed. The 
            type can be set with 
            SetType=
            type 
External programs must be on a trusted path (see Section 10.1 ), i.e. must not be writeable by untrusted users.
For enhanced security, the (192-bit TIGER)
            checksum of the external program/script may be
            specified in the configuration file: 
            SetChecksum=
            checksum (one
            string, no blanks in checksum)
Command line arguments and environment variables for each external program are configurable (the default is no command line arguments, and a clean environment containing only the TZ (timezone) variable:
            SetCommandline=
            
            full_command_line (full command
            line starting with the name of the program)
              Setenviron=
              KEY=value 
            
The user whose credentials shall be used, can be
            specified: 
            SetCredentials=
            username 
Some filters are available to make the execution of an external program dependent on the message content:
            SetFilterNot=
            list If any regular
            expression in 'list' matches the message, the program
            is not executed, else
            SetFilterAnd=
            list if any regular
            expression in 'list' is not matching the message, the
            program is not executed, else
            SetFilterOr=
            list if none of the
            regular expressions in 'list' matches the message, the
            program is not executed.
For all filters, list items can be quoted with single or double quotes. It is also possible to use each filter option multiple times, although this does not affect the order (not, and, or) in which filters are evaluated. A maximum of 32 filter patterns for each of (not, and. or) are supported per defined external program. Any filter not defined is not evaluated.
It is possible to set a 'deadtime'. Within that
            'deadtime', the respective external program will be
            executed only once (if triggered): 
            SetDeadtime=
            seconds 
The distribution contains two example perl scripts for paging and SMS messages (example_pager.pl, example_sms.pl). The paging script will page via a web CGI script at www.pagemart.com (obviously will work only for their pagers), the SMS script is for any German 'free SMS' web site that outsources free SMS to pitcom (with a suitable query on Google you can find such sites; you can then inspect the HTML form to set proper values for the required form variables.)
If you know some Perl, both scripts can be adapted fairly easily to other providers. Below is an example setup for calling example_pager.pl as an external logging facility.
[External] # start definition of first external program OpenCommand=/usr/local/bin/example_pager.pl SetType=log # arguments SetCommandline=example_pager.pl pager_id # environment SetEnviron=HOME=/home/moses SetEnviron=PATH=/bin:/usr/bin:/usr/local/bin # checksum SetChecksum=FCBD3377B65F92F1701AFEEF3B5E8A80ED4936FD0D172C84 # credentials SetCredentials=moses # filter SetFilterOr=POLICY # deadtime SetDeadtime=3600 #Optional CloseCommand