The kick in the butt for unreliable programs
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Emiel Kollof 82b806825a Compat code 11 years ago
examples Initial commit 12 years ago
src Compat code 11 years ago
testprg Initial commit 12 years ago
BUGS Initial commit 12 years ago
Changelog Initial commit 12 years ago
HACKING Initial commit 12 years ago
Makefile Initial commit 12 years ago
README Removed old address, and I don't wish to share my new address. 12 years ago
TODO Initial commit 12 years ago
WISHLIST Initial commit 12 years ago

README

Angel - The kick in the butt for unreliable programs
----------------------------------------------------

Author: Emiel Kollof <coolvibe@hackerheaven.org>
License: BSD
Date: Mon Dec 1 19:40:10 CET 2003
CVSid: $Id: README,v 1.5 2003/12/09 19:48:42 coolvibe Exp $

Description:
------------

Angel is a program that executes any other program you need, and then restarts
that program when it ends or crashes. Angel can run in foreground and daemon
mode. In foreground mode, angel doesn't go to the background. In daemon mode,
it goes quietly to the background and keeps your selected program running.

When angel is running, you can control what angel does through commandfiles.
These are chosen at compile-time. Examine the Makefile in the src/ directory
if you'd like to use different names. Through these files you can kill, renice
or stop angel from restarting your selected program.

Angel uses configuration files in which you can set the program to be executed,
the arguments you want to give it, tune delays and resource stuff.

Why did you write this?:
------------------------

In most places, unreliable programs are kept alive by so-called angel-scripts.
A well known example is the safe_mysqld script from the MySQL RDBMS. Angel
is an attempt to do away with all this custom hacking, and to be a general
purpose angel to unreliable programs.

Requirements:
-------------

A C compiler, a make(1) utility. The C compiler must be able to grok ANSI and
ISO C99 C. POSIX compatibility would be nice too, since I need fork() and the
wait* family of syscalls. Tested on BSD-derivative systems only. On anything
else YMMV, but it should be a quick port if you know how :). Also tested BSD
make and GNU make, both seem to work fine. Tested with GNU C (gcc) and the
Intel C/C++ compiler (icc).

How to install:
---------------

Unpack the angel tarball somewhere and cd into the directory that gets
created. Run make. Watch the short compile. Rejoice if there are no errors.
Type `make install`.

Typically, angel gets installed in /usr/local. If you don't like it, copy
angel from the src/ dir to a place you'd like to see it.

There, angel is installed. Now let's set it up.

Angel looks for configuration files in two directories. It looks first in
~/.angel, and if that fails, it looks in /etc/angel. Create one of those
two directories. For added security, I recommend that you set the workdir
to a dir only _you_ can write to (not /tmp, like in the example). Just create
a workdir in your $HOME and set it to mode 700 and use that.

Now create a configuration file in the configuration dir, and name it exactly
like the program you are trying to run. For instance, if you want to angelicize
xterm, you call the configfile `xterm`. In the configfile, you set all the
variables the way you want. Commenting out a var is safe, but the exec and argv
parameters are mandatory. Examples are in the examples/ directory.

Symlink the name of your program to angel like so:

$ ln -s /path/to/angel programname

Instead of running the program, run the symlink, and voila, your program
is angelicized.

Now, let's explain how to control angel's behaviour:

Angel works with commandfiles. Files you can create in the working directory,
which angel picks up on, and reacts to. Here are some examples.

1. My program is locked up, and it's still running. I want angel to kill it.

Very simple. Observe:

$ cd $workdir
$ echo 9 > .kill

Angel will pick up on the file, and will send signal 9 to the angelicized
process. It will unlink the command file when it's done.

2. I want to lower my program's priority (renice)

Like .kill, use .nice like so:

$ echo 10 > .nice

Angel will use the setpriority() call to set the niceness.

3. My program is going mad! I want angel to stop re-executing my program
until I fix it!

Touch a file named .stop in the $workdir. Angel will hold off forking until
you remove the .stop file.

I hope that explains a litte what angel can do. It's been handy for me, and
I hope it will be handy for you. Admissions of gratitude can be expressed to
me through e-mail, hardware, beer and postcards. Voluntary ofcourse :)

Troubleshooting FAQ:
--------------------

Q: I still have no fscking clue about how to use this
A: Read the manual again, and again, until you get it. It helps to play
around with angel.

Q: Angel is a HUGE security hole! Anyone can control the process!
A: Like I said, make sure the workdir is writable by you alone. Angel
does not drop privs (although I might hack that in if people want it),
so any code you execute with angel will run with the same privs that
angel runs with. Running setuid binaries with angel is _not recommended_.
Installing angel with setuid privs is a definite nono.

Hacking FAQ:
------------

Q: I have this great patch for angel which adds cool new functionality.
A: That's great! Send it to me, and I'll include it in the patches/
directory of the distribution. Be sure to document what your patch
adds. If it's cool enough, and doesn't break things, it might even end
up in angel itself. Of yourse you get full credit.

Q: Angel didn't compile on my platform, so here's a patch that fixes this.
A: If it doesn't break other platform builds, then it will go into angel
itself. If it does, I will put the patch in the patches/ subdir.

Q: Here's a patch to make angel compile with <some non-GNU compatible
compiler>.
A: Thanks. In the patches/ subdir it goes, unless you figure out a way to
not break compilation on other systems. Using GNU autotools is NOT an
option. I will not maintain that. Fork this project if you desperately
want that.

Q: Why don't you want to use the GNU autotools suite?
A: Because I hate those with a passion. I'll keep using plain makefiles
until a straightforward build system comes along that is easy to
implement, is cross-platform/compiler and isn't full of cruft.

Q: That's a nice program you got there. Mind if I...?
A: Sure, go ahead. It's BSD licensed, so you can pretty much do with
this what you want. Except for claiming that you wrote it yourself and
removing the copyright notices on the headers and source.

Q: I like the makefiles, and I notice that they don't have a license
attached. Does that mean I can 'steal' those?
A: Sure, do whatever gets you off.

Author contact info:
--------------------

Emiel Kollof <coolvibe@hackerheaven.org>