Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 op-
	      tion 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  op-
	      tion  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-in-
       dependent 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 in-
       stalled 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | EXAMPLE | NOTES | EXIT STATUS | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=runchoom&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help