filters/exitwhen/nbdkit-exitwhen-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-exitwhen-filter - exit gracefully when an event occurs
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=exitwhen PLUGIN
   8                           [exit-when-file-created=FILENAME]
   9                           [exit-when-file-deleted=FILENAME]
  10                           [exit-when-pipe-closed=FD]
  11                           [exit-when-process-exits=PID]
  12                           [exit-when-script=SCRIPT]
  13                           [exit-when-poll=SECS]
  14
  15 =head1 DESCRIPTION
  16
  17 C<nbdkit-exitwhen-filter> is an nbdkit filter that causes nbdkit to
  18 exit gracefully when some external event occurs.  Built-in events are:
  19 a file being created or deleted, a pipe being closed, or a process
  20 exiting.  You can also define custom events using an external script
  21 or command.
  22
  23 After the event occurs nbdkit refuses new connections, waits for all
  24 current clients to disconnect, and then exits.
  25
  26 A similar filter is L<nbdkit-exitlast-filter(1)>.  For other ways to
  27 ensure that nbdkit exits when you want see L<nbdkit-captive(1)> and
  28 L<nbdkit-service(1)>.
  29
  30 =head1 EXAMPLES
  31
  32  nbdkit --filter=exitwhen memory 1G exit-when-file-created=/tmp/stop
  33
  34 nbdkit will run normally until something creates F</tmp/stop>,
  35 whereupon nbdkit will refuse new connections and exit as soon as the
  36 last client has disconnected.  If F</tmp/stop> exists before nbdkit
  37 starts, it will exit immediately.
  38
  39  nbdkit --filter=exitwhen memory 1G exit-when-process-exits=1234
  40
  41 nbdkit will exit gracefully when PID 1234 exits and all connections
  42 close.  If you want to exit when the parent process of nbdkit exits,
  43 consider using the I<--exit-with-parent> flag instead.
  44
  45 =head1 PARAMETERS
  46
  47 You can define multiple C<exit-when-*> events on the command line:
  48 nbdkit will exit if any of the events happens.  If there are no
  49 C<exit-when-*> events then the filter does nothing.
  50
  51 =over 4
  52
  53 =item B<exit-when-file-created=>FILENAME
  54
  55 =item B<exit-when-file-deleted=>FILENAME
  56
  57 Exit when the named file is created or deleted.
  58
  59 =item B<exit-when-pipe-closed=>FD
  60
  61 The read end of a L<pipe(2)> is passed to nbdkit in the given file
  62 descriptor number.  Exit when the pipe is closed.  The filter does not
  63 read any data from the pipe.
  64
  65 For an example of how to use this parameter, see:
  66 L<https://gitlab.com/nbdkit/nbdkit/-/blob/master/tests/test-exitwhen-pipe-closed.c>
  67
  68 =item B<exit-when-process-exits=>PID
  69
  70 Exit when process ID C<PID> exits.
  71
  72 Note there is a small race between passing the process ID to the
  73 filter and the filter checking it for the first time.  During this
  74 window the original PID might exit and an unrelated program might get
  75 the same PID, thus holding nbdkit open for longer than wanted.  The
  76 pipe method above is more reliable if you are able to modify the other
  77 process.
  78
  79 =item B<exit-when-script=">SCRIPTB<">
  80
  81 Create a custom event using the script or command C<SCRIPT>.  The
  82 C<SCRIPT> can be a program, shell script or a command with optional
  83 parameters.  Note if using a filename here: you may need to use the
  84 absolute path because nbdkit changes directory when it daemonizes.
  85
  86 The script should exit with code 88 if the event is detected.  The
  87 filter does different things depending on the exit code of the script:
  88
  89 =over 4
  90
  91 =item C<0>
  92
  93 I<The event has not been triggered>, so nbdkit continues to process
  94 requests as normal.
  95
  96 =item C<1-87>
  97
  98 An error is logged, but the event is I<not> triggered and nbdkit
  99 continues to process requests as normal.
 100
 101 =item C<88>
 102
 103 I<The event has been triggered>.  nbdkit will refuse new connections
 104 and exit gracefully as soon as all current clients disconnect.
 105
 106 =item C<89->
 107
 108 Exit codes 89 and above are reserved for future use.  The behaviour
 109 may change in future if scripts return any of these exit codes.
 110
 111 =back
 112
 113 =item B<exit-when-poll=>SECS
 114
 115 When nbdkit is serving clients this filter does not need to poll
 116 because it can check for events when a client connects or disconnects.
 117 However when nbdkit is idle the filter needs to poll for events every
 118 C<SECS> seconds and if any event happens exit immediately.
 119
 120 The default is 60 seconds.
 121
 122 =back
 123
 124 =head1 NOTES
 125
 126 =head2 Compared to I<--exit-with-parent>
 127
 128 The nbdkit server option I<--exit-with-parent> causes nbdkit to exit
 129 when the parent process exits.  It seems similar to:
 130
 131  nbdkit --filter=exitwhen ... exit-when-process-exits=$$
 132
 133 (C<$$> is the parent PID of nbdkit).
 134
 135 But there are significant differences caused by the implementation.
 136 I<--exit-with-parent> is implemented using the Linux feature
 137 C<PR_SET_PDEATHSIG> (C<PROC_PDEATHSIG_CTL> on FreeBSD).  This causes a
 138 signal to be sent to the server when the parent process dies.  On
 139 receiving the signal nbdkit closes client connections and terminates
 140 at once.
 141
 142 On the other hand C<exit-when-process-exits> monitors the other
 143 process (which does not need to be the parent) and shuts down the
 144 server in a different way: currently open connections are allowed to
 145 continue until they close.
 146
 147 Neither of these methods is completely reliable in all cases: signals
 148 can be lost and there is a possible (albeit very small) race when
 149 passing the PID to C<exit-when-process-exits>.  More reliable methods
 150 of clean up are C<exit-when-pipe-closed> or putting all of the
 151 processes into a cgroup.  (See L<nbdkit-captive(1)> and
 152 L<nbdkit-service(1)>).
 153
 154 =head1 FILES
 155
 156 =over 4
 157
 158 =item F<$filterdir/nbdkit-exitwhen-filter.so>
 159
 160 The filter.
 161
 162 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 163
 164 =back
 165
 166 =head1 VERSION
 167
 168 C<nbdkit-exitwhen-filter> first appeared in nbdkit 1.24.
 169
 170 =head1 SEE ALSO
 171
 172 L<nbdkit(1)>,
 173 L<nbdkit-exitlast-filter(1)>,
 174 L<nbdkit-ip-filter(1)>,
 175 L<nbdkit-limit-filter(1)>,
 176 L<nbdkit-rate-filter(1)>,
 177 L<nbdkit-captive(1)>,
 178 L<nbdkit-service(1)>,
 179 L<nbdkit-filter(3)>,
 180 L<nbdkit-plugin(3)>.
 181
 182 =head1 AUTHORS
 183
 184 Richard W.M. Jones
 185
 186 =head1 COPYRIGHT
 187
 188 Copyright Red Hat