1nbdkit-pause-filter(1)              NBDKIT              nbdkit-pause-filter(1)
2
3
4

NAME

6       nbdkit-pause-filter - pause NBD requests
7

SYNOPSIS

9        nbdkit --filter=pause PLUGIN [PLUGIN-ARGS...] pause-control=SOCKET
10

DESCRIPTION

12       "nbdkit-pause-filter" is a filter for nbdkit(1) which can temporarily
13       stop NBD requests from being handled by nbdkit, and later resume them.
14       This filter can be used if you need to take a snapshot of the
15       underlying storage.
16
17   Control socket
18       The "pause-control" parameter is the name of a Unix domain socket which
19       the filter listens for commands on.
20
21       To pause NBD request processing you send character 'p' to the socket.
22       Any NBD requests received afterwards will hang until you resume
23       processing.
24
25       To resume processing you send character 'r' to the socket.
26
27       So you can know when pausing/resuming has taken effect, the filter
28       echos back the character over the socket in uppercase (ie. either 'P'
29       or 'R').  When pausing, the 'P' response is not sent until all
30       outstanding NBD requests (received before the pause) have been
31       completed.  This usually means the plugin is idle, although be aware
32       that it is possible for plugins to create background threads and do
33       work that the filter cannot "see".
34
35       Any unknown commands are ignored.  The filter responds with 'X'.
36

EXAMPLE

38       Pick a large file, disk image or ISO, serve it over NBD, and start
39       copying it:
40
41        nbdkit --filter=pause --filter=rate \
42          file BIG_FILE.ISO rate=10M pause-control=sock \
43               --run 'qemu-img convert -p $nbd /var/tmp/out'
44
45       To cause the copy to appear to hang, do:
46
47        echo p | nc -U sock
48
49       To resume activity:
50
51        echo r | nc -U sock
52

PARAMETERS

54       pause-control=SOCKET
55           The Unix domain socket for controlling the filter.  See "Control
56           socket" above.
57

NOTES

59       If you are connecting a kernel client, virtual machine or similar to
60       nbdkit then only short pauses are tolerated, and you will soon get
61       timeout errors.  The timeouts are not generated by nbdkit, but by the
62       client itself.
63
64       The pause filter does not flush requests to disk, although this is a
65       possible future enhancement.
66
67       A virtual machine with multiple disks connected through multiple nbdkit
68       instances cannot get a consistent snapshot using this filter, since
69       even if you send the pause commands to all instances at the same time
70       they will be processed at slightly different times (and this can matter
71       if a virtual machine is doing something like RAID across the disks).
72       This is not something that can be solved at the level of individual
73       devices, the only way to solve this is at the hypervisor level.
74

FILES

76       $filterdir/nbdkit-pause-filter.so
77           The filter.
78
79           Use "nbdkit --dump-config" to find the location of $filterdir.
80

VERSION

82       "nbdkit-pause-filter" first appeared in nbdkit 1.22.
83

SEE ALSO

85       nbdkit(1), nbdkit-filter(3), nbdkit-delay-filter(1),
86       nbdkit-rate-filter(1), nc(1).
87

AUTHORS

89       Richard W.M. Jones
90

92       Copyright Red Hat
93

LICENSE

95       Redistribution and use in source and binary forms, with or without
96       modification, are permitted provided that the following conditions are
97       met:
98
99       •   Redistributions of source code must retain the above copyright
100           notice, this list of conditions and the following disclaimer.
101
102       •   Redistributions in binary form must reproduce the above copyright
103           notice, this list of conditions and the following disclaimer in the
104           documentation and/or other materials provided with the
105           distribution.
106
107       •   Neither the name of Red Hat nor the names of its contributors may
108           be used to endorse or promote products derived from this software
109           without specific prior written permission.
110
111       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
112       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
113       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
114       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
115       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
116       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
117       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
118       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
119       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
120       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
121       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
122
123
124
125nbdkit-1.36.2                     2023-11-26            nbdkit-pause-filter(1)
Impressum