NAME

runchoom - abate linux oom killer on a process

SYNOPSIS

runchoom [-hV] [-ev] [-b base ] [-k key ] [-p pid ] [-s str ] program [ args ... ]

DESCRIPTION

runchoom writes the string ``-17'' and a newline into the procfile /proc/<pid>/oom_adj, where <pid> is the process id of runchoom. It then execs program with any arguments given in args.

If program does not contain a ``/'' slash character, runchoom will perform a shell-like search for the executable using the PATH variable in the current environment.

OPTIONS

-b base: Base directory. Normally runchoom uses the compiled-in default value /proc for the initial path element of the target procfile. The -b option may be used to specify an alternative, and should be given with a leading `/'. This option overrides any definition of CHOOM_BASE in the environment.
-e: Error fail. Normally runchoom ignores any of the following conditions and proceeds to exec program anyway: the target procfile does not exist; the target procfile cannot be opened or written to. By specifying the -e option, runchoom will instead fail at any of these conditions, and not proceed to exec program.
-h: Help. Print a brief usage message to stderr and exit.
-k key: Key. Normally runchoom uses the compiled-in default value oom_adj for the last element of the target procfile. The -k option may be used to specify an alternative. This option overrides any definition of CHOOM_KEY in the environment.
-p pid: Pid. Normally runchoom uses the value returned by getpid(2) to determine the <pid> element of the target procfile. The -p option may be used to specify an alternative, and should be given as a numeric value.
-s str: Setting. Normally runchoom uses the compiled-in default string ``-17'' as the setting to write into the target procfile. The -s option may be used to specify an alternative. This option overrides any definition of CHOOM_SET in the environment. Note that runchoom adds a terminal newline to any string written into the target procfile.
-v: Verbose. Normally runchoom runs quietly. The -v option may be used to generate some messages to stderr.
-V: Version. Print the version number to stderr and exit.

ENVIRONMENT

The following environmental variables are inspected if they are not otherwise specified on the command-line, and may be used to override the compiled-in defaults:

CHOOM_BASE

The initial path element of the target procfile.

CHOOM_KEY

The final path element of the target procfile.

CHOOM_SET

The string to write into the target procfile. Note that runchoom adds a terminal newline to any string written into the target procfile.

EXAMPLE

The runchoom utility was specifically designed to protect an instance of perpd(8) from the SIGKILLs generated by a linux kernel (from 2.6.11) when it is attempting to free up system resources from an overcommitment of memory. However, the utility is implemented in a platform-independent sense such that, by default, it has no effect (and no failure) on any system where the target procfile is not present.

Its primary usage is intended within the rc.perp bootscript run by the perpboot(8) utility. The following script can normally be used verbatim on any platform:

#!/bin/sh -e
# rc.perp: perpd startup script for perpboot
# ===
### --- configure ---
PERPD_OPTS="-a6"
## exec perpd:
##   * options as configured above
##   * runchoom(8) abate linux oom-killer
##   * runlimit(8) configured in ./rlimit.conf
##   * PERP_BASE defined in environment by perpboot(8)
exec \
  runchoom \
  runlimit -F ./rlimit.conf \
  perpd ${PERPD_OPTS} ${PERP_BASE}
### EOF

NOTES

On a system where the oom_adj procfile is operative, the setting installed by runchoom will be inherited by all child processes. As shown in the above example, then, all the individual services running under the perpd(8) process tree will acquire the -17 setting for ``oom killer'' abatement.

Presumably this is desirable. If not, the runchoom utility may be used within the individual perpetrate(5) runscripts of any selected services to reset the oom_adj parameter of a process to a default state:

#!/bin/sh
  ...
  exec \
  runchoom -s "0" \
  myservice ...
### EOF

EXIT STATUS

runchoom exits with one of the following values:

0: program was invoked and completed successfully. In this case, the exit code is returned by the program, rather than by runchoom itself.
100: runchoom failed because of a usage error, such as an invalid command-line option or argument. In this case, runchoom prints a brief error message and usage help to stderr on exit.
111: runchoom failed due to some system or resource error. In this case, runchoom prints a brief diagnostic message to stderr on exit.
1-127: program was invoked and failed with its own non-zero exit status.

BUGS

The need for this utility.

AUTHOR

Wayne Marshall, http://b0llix.net/perp/