GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
runchoom(8) runtools runchoom(8)

runchoom - abate linux oom killer on a process

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

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.

-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.

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.

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

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

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.

The need for this utility.

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

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)
January 2013 runtools-2.07

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.