oasis-root

runchoom.8 (5695B)

.\" runchoom.8
.\" wcm, 2011.03.18 - 2011.03.22
.\" ===
.TH runchoom 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runchoom \- abate linux oom killer on a process
.SH SYNOPSIS
.B runchoom [\-hV] [-ev] [\-b
.I base
.B ] [\-k
.I key
.B ] [\-p
.I pid
.B ] [\-s
.I str
.B ]
.I program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runchoom
writes the string ``-17'' and a newline into the procfile
.IR /proc/<pid>/oom_adj ,
where
.I <pid>
is the process id of
.BR runchoom .
It then execs
.I program
with any arguments given in
.IR args .
.PP
If
.I program
does not contain a ``/'' slash character,
.B runchoom
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.SH OPTIONS
.TP
.B \-b base
Base directory.
Normally
.B runchoom
uses the compiled-in default value
.I /proc
for the initial path element of the target procfile.
The
.B \-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.
.TP
.B \-e
Error fail.
Normally
.B runchoom
ignores any of the following conditions and proceeds to exec
.I program
anyway:
the target procfile does not exist;
the target procfile cannot be opened or written to.
By specifying the
.B \-e
option,
.B runchoom
will instead fail at any of these conditions,
and not proceed to exec
.IR program .
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-k key
Key.
Normally
.B runchoom
uses the compiled-in default value
.I oom_adj
for the last element of the target procfile.
The
.B \-k
option may be used to specify an alternative.
This option overrides any definition of CHOOM_KEY in the environment.
.TP
.B \-p pid
Pid.
Normally
.B runchoom
uses the value returned by
.BR getpid (2)
to determine the
.I <pid>
element of the target procfile.
The
.B \-p
option may be used to specify an alternative,
and should be given as a numeric value.
.TP
.B \-s str
Setting.
Normally
.B runchoom
uses the compiled-in default string ``-17'' as the setting to write
into the target procfile.
The
.B \-s
option may be used to specify an alternative.
This option overrides any definition of CHOOM_SET in the environment.
Note that
.B runchoom
adds a terminal newline to any string written into the target procfile.
.TP
.B \-v
Verbose.
Normally
.B runchoom
runs quietly.
The
.B \-v
option may be used to generate some messages to stderr.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH 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:
.PP
CHOOM_BASE
.RS
The initial path element of the target procfile.
.RE
.PP
CHOOM_KEY
.RS
The final path element of the target procfile.
.RE
.PP
CHOOM_SET
.RS
The string to write into the target procfile.
Note that
.B runchoom
adds a terminal newline to any string written into the target procfile.
.RE
.SH EXAMPLE
The
.B runchoom
utility was specifically designed to protect an instance of
.BR 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.
.PP
Its primary usage is intended within the
.I rc.perp
bootscript run by the
.BR perpboot (8)
utility.
The following script can normally be used verbatim on any platform:
.PP
.RS
.nf
#!/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
.fi
.RE
.SH NOTES
On a system where the
.I oom_adj
procfile is operative,
the setting installed by
.B runchoom
will be inherited by all child processes.
As shown in the above example, then,
all the individual services running under the
.BR perpd (8)
process tree will acquire the -17 setting for ``oom killer'' abatement.
.PP
Presumably this is desirable.
If not, the
.B runchoom
utility may be used within the individual
.BR perpetrate (5)
runscripts of any selected services to
reset the
.I oom_adj
parameter of a process to a default state:
.PP
.RS
.nf
#!/bin/sh
  ...
  exec \\
  runchoom -s "0" \\
  myservice ...
### EOF
.fi
.RE 
.SH EXIT STATUS
.B runchoom
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runchoom
itself.
.TP
100
.B runchoom
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runchoom
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runchoom
failed due to some system or resource error.
In this case,
.B runchoom
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH BUGS
The need for this utility.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlimit (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8),
.BR perpd (8),
.BR perpboot (8),
.BR proc (5)
(on relevant platforms)
.\" EOF