usr.bin/protect/protect.1

   1 .\" Copyright (c) 2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd July 12, 2022
  27 .Dt PROTECT 1
  28 .Os
  29 .Sh NAME
  30 .Nm protect
  31 .Nd "protect processes from being killed when swap space is exhausted"
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl i
  35 .Ar command
  36 .Nm
  37 .Op Fl cdi
  38 .Fl g Ar pgrp
  39 .Nm
  40 .Op Fl cdi
  41 .Fl p Ar pid
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 command is used to mark processes as protected.
  46 The kernel does not kill protected processes when swap space is exhausted.
  47 Note that this protected state is not inherited by child processes by default.
  48 .Pp
  49 The options are:
  50 .Bl -tag -width command
  51 .It Fl c
  52 Remove protection from the specified processes.
  53 .It Fl d
  54 Apply the operation to all current children of the specified processes.
  55 .It Fl i
  56 Apply the operation to all future children of the specified processes.
  57 .It Fl g Ar pgrp
  58 Apply the operation to all processes in the specified process group.
  59 .It Fl p Ar pid
  60 Apply the operation to the specified process.
  61 .It Ar command
  62 Execute
  63 .Ar command
  64 as a protected process.
  65 .El
  66 .Pp
  67 Note that only one of the
  68 .Fl p
  69 or
  70 .Fl g
  71 flags may be specified when adjusting the state of existing processes.
  72 .Pp
  73 Daemons can be protected on startup using
  74 .Ao Ar name Ac Ns Va _oomprotect
  75 option from
  76 .Xr rc.conf 5 .
  77 .Sh EXIT STATUS
  78 .Ex -std
  79 .Sh EXAMPLES
  80 Mark the Xorg server as protected:
  81 .Pp
  82 .Dl "pgrep Xorg | xargs protect -p"
  83 .Pp
  84 Protect all ssh sessions and their child processes:
  85 .Pp
  86 .Dl "pgrep sshd | xargs protect -dip"
  87 .Pp
  88 Remove protection from all current and future processes:
  89 .Pp
  90 .Dl "protect -cdi -p 1"
  91 .Pp
  92 Using
  93 .Xr ps 1
  94 to check if the protect flag has been applied to the process:
  95 .Pp
  96 .Dl "ps -O flags,flags2 -p 64430"
  97 .Pp
  98 .Dl " PID        F       F2 TT  STAT    TIME COMMAND"
  99 .Dl "64430 10104002 00000001  5  S+   0:00.00 ./main"
 100 .Dl "        ^P            ^PI"
 101 .Pp
 102 In the above example
 103 .Nm P
 104 points at the protected flag and
 105 .Nm PI
 106 points at the inheritance flag.
 107 The process is protected if
 108 .Nm P
 109 bit is set to 1.
 110 All children of this process will also be protected if
 111 .Nm PI
 112 bit is set to 1.
 113 .Sh DIAGNOSTICS
 114 .Bl -diag
 115 .It "protect: procctl: Operation not permitted"
 116 The
 117 .Nm
 118 command does not have the required permissions to protect selected processes.
 119 There are many reasons why this could be the case, e.g.:
 120 .Bl -dash
 121 .It
 122 .Nm
 123 is not executed by root.
 124 .It
 125 .Nm
 126 is executed inside a
 127 .Xr jail 8 ,
 128 which is not supported at the moment.
 129 .El
 130 .El
 131 .Sh SEE ALSO
 132 .Xr ps 1 ,
 133 .Xr procctl 2 ,
 134 .Xr rc.conf 5
 135 .Sh BUGS
 136 If you protect a runaway process that allocates all memory the system will
 137 deadlock.