Documentation for "expecto"

Download the whole documentation as one plain text file


2. Requirements and Installation

Technical Requirements

Operating System:

This software was written with FreeBSD in mind, but it should work on any POSIX-conformant system, including other BSD variants, Linux distributions and commercial UNIX systems like Solaris. Please let me know if there's an incompatibility with your operating system.

Programming Language:

The expecto utility is written in the Python programming language. Therefore you must have a recent version of Python 2.x installed. At the time of this writing, 2.7 is the recommended version. (Note: Python 3.x is currently not compatible with expecto.)

If you're not sure, just type "python" in a terminal window. Among other things, it will display the Python version, e.g. "Python 2.7.3". Press Ctrl-D to exit from the Python prompt. Note: On some systems both Python 2.x and 3.x are installed -- in this case you might have to type "python2" or "python27" to get the right version.

If your python binary is not installed in /usr/local/bin, you have to adapt the first line of the expecto script: Open it in a standard text editor and make sure that the full path of your python 2.x binary is entered in the first line after the "#!" character sequence.

Human Requirements

Regular Expressions:

You have to be familiar with regular expressions. In order be useful, expecto requires you to create template files. These templates make use of regular expressions. While the template syntax is explained here, the syntax and meaning of regular expressions is beyond the scope of this document. There are several good tutorials on the internet; just use a search engine.

By the way, expecto uses Python's regular expression library that implements a superset of so-called extended regular expressions. However, for most purposes it is sufficient to know that expecto supports the same expressions that can be used with the egrep utility. (Refer to the egrep(1) manual page on your system. If that doesn't exist, refer to the -E option in the grep(1) manual page; note that egrep is just a shortcut for "grep -E".)

Cron:

You also have to be familiar with cron, i.e. how the cron daemon works and how to create and modify crontab entries. Of course this doesn't apply if you intend to use expecto for something other than cron jobs.

Time:

This is a fairly important thing that you need to be aware of: Be prepared to spend some time reading through this documentation completely. You won't be able to use expecto successfully within five minutes. The syntax of the template files is very powerful, but that means it is somewhat complex. But the time spent is well worth it: When used cleverly, it can reduce the amount of your cron mails considerably.

Installation

Normally you'll want to install expecto as root. The suggested target directory is /usr/local/sbin, but you can install it anywhere you like.

However, you can also install expecto as a normal user (for example to "$HOME/bin"). It does not require root permission per-se. In this case you can only use it to filter your own user cron jobs.

The expecto utility consists of two files:

Simply download them both from the links above and store them in the target directory. Make sure that they are executable by root by typing these commands after downloading:

chmod 755 expecto expecto_expr.py chown 0:0 expecto expecto_expr.py

You should also check the first line of expecto. In the original distribution it looks like this:

#!/usr/local/bin/python

If your python binary is not located in /usr/local/bin, you need to change that line (use a standard text editor). If in doubt, you can use the command "where python" or "type python" (depending on your shell) to find out where your python binary is located. Also, on some systems you have to use "python2" (or even "python27") to get the correct version of the python binary, particularly if there is another version (such as 3.x) installed at the same time.

That's all. I'm sorry there is no install script or anything, but I think this is simple enough that you won't need it. When you're done, check that expecto can be executed by typing "expecto" at the shell prompt. It should respond with the following error message:

expecto: Usage error. Try "expecto -h" for help.

If you get a different error message, try typing "./expecto" instead. If this works, then the directory is not in your standard search path ("$PATH"). If it doesn't work either, there's probably something wrong with your Python installation. Check that the python directory is correct (see above).



[Valid XHTML 1.0]