runchoom(8) runtools runchoom(8)
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 per-
form 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 defini-
tion of CHOOM_BASE in the environment.
-e Error fail. Normally runchoom ignores any of the following con-
ditions 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 over-
rides 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 run-
choom 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 overcommit-
ment of memory. However, the utility is implemented in a platform-
independent sense such that, by default, it has no effect (and no fail-
ure) 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 verba-
tim 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 run-
choom 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 sta-
tus.
BUGS
The need for this utility.
AUTHOR
Wayne Marshall, http://b0llix.net/perp/
SEE ALSO
runtools_intro(8), runargs(8), runargv0(8), rundetach(8), rundeux(8),
runenv(8), runfile(8), runlimit(8), runlock(8), runpause(8),
runsession(8), runtool(8), runtrap(8), runuid(8), perpd(8),
perpboot(8), proc(5) (on relevant platforms)
runtools-2.07 January 2013 runchoom(8)