xref: /freebsd/lib/geom/nop/gnop.8 (revision 51f61fc0c7ece7a30c737341e65455841bc3f04e)
1.\" Copyright (c) 2004-2006 Pawel Jakub Dawidek <pjd@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd July 31, 2019
28.Dt GNOP 8
29.Os
30.Sh NAME
31.Nm gnop
32.Nd "control utility for NOP GEOM class"
33.Sh SYNOPSIS
34.Nm
35.Cm create
36.Op Fl v
37.Op Fl d Ar delaymsec
38.Op Fl e Ar error
39.Op Fl o Ar offset
40.Op Fl p Ar stripesize
41.Op Fl P Ar stripeoffset
42.Op Fl q Ar rdelayprob
43.Op Fl r Ar rfailprob
44.Op Fl s Ar size
45.Op Fl S Ar secsize
46.Op Fl w Ar wfailprob
47.Op Fl x Ar wdelayprob
48.Op Fl z Ar physpath
49.Ar dev ...
50.Nm
51.Cm configure
52.Op Fl v
53.Op Fl d Ar delaymsec
54.Op Fl e Ar error
55.Op Fl q Ar rdelayprob
56.Op Fl r Ar rfailprob
57.Op Fl w Ar wfailprob
58.Op Fl x Ar wdelayprob
59.Ar prov ...
60.Nm
61.Cm destroy
62.Op Fl fv
63.Ar prov ...
64.Nm
65.Cm reset
66.Op Fl v
67.Ar prov ...
68.Nm
69.Cm list
70.Nm
71.Cm status
72.Nm
73.Cm load
74.Nm
75.Cm unload
76.Sh DESCRIPTION
77The
78.Nm
79utility is used for setting up transparent providers on existing ones.
80Its main purpose is testing other GEOM classes, as it allows forced provider
81removal and I/O error simulation with a given probability.
82It also gathers statistics on the number of read, write, delete,
83getattr, flush, and other requests, and the number of bytes read and written.
84.Nm
85can also be used as a good starting point for implementing new GEOM
86classes.
87.Pp
88The first argument to
89.Nm
90indicates an action to be performed:
91.Bl -tag -width ".Cm configure"
92.It Cm create
93Set up a transparent provider on the given devices.
94If the operation succeeds, the new provider should appear with name
95.Pa /dev/ Ns Ao Ar dev Ac Ns Pa .nop .
96The kernel module
97.Pa geom_nop.ko
98will be loaded if it is not loaded already.
99.It Cm configure
100Configure existing transparent provider.
101At the moment it is only used for changing failure probability.
102.It Cm destroy
103Turn off the given transparent providers.
104.It Cm reset
105Reset statistics for the given transparent providers.
106.It Cm list
107See
108.Xr geom 8 .
109.It Cm status
110See
111.Xr geom 8 .
112.It Cm load
113See
114.Xr geom 8 .
115.It Cm unload
116See
117.Xr geom 8 .
118.El
119.Pp
120Additional options:
121.Bl -tag -width ".Fl r Ar rfailprob"
122.It Fl d Ar delaymsec
123Specifies the delay of the requests in milliseconds.
124Note that requests will be delayed before they are sent to the backing device.
125.It Fl e Ar error
126Specifies the error number to return on failure.
127.It Fl f
128Force the removal of the specified provider.
129.It Fl o Ar offset
130Where to begin on the original provider.
131.It Fl p Ar stripesize
132Value of the stripesize property of the transparent provider.
133.It Fl P Ar stripeoffset
134Value of the stripeoffset property of the transparent provider.
135.It Fl q Ar rdelayprob
136Specifies read delay probability in percent.
137.It Fl r Ar rfailprob
138Specifies read failure probability in percent.
139.It Fl s Ar size
140Size of the transparent provider.
141.It Fl S Ar secsize
142Sector size of the transparent provider.
143.It Fl w Ar wfailprob
144Specifies write failure probability in percent.
145.It Fl v
146Be more verbose.
147.It Fl x Ar wdelayprob
148Specifies write delay probability in percent.
149.It Fl z Ar physpath
150Physical path of the transparent provider.
151.El
152.Sh SYSCTL VARIABLES
153The following
154.Xr sysctl 8
155variables can be used to control the behavior of the
156.Nm NOP
157GEOM class.
158The default value is shown next to each variable.
159.Bl -tag -width indent
160.It Va kern.geom.nop.debug : No 0
161Debug level of the
162.Nm NOP
163GEOM class.
164This can be set to a number between 0 and 2 inclusive.
165If set to 0, minimal debug information is printed.
166If set to 1, basic debug information is logged along with the I/O requests
167that were returned as errors.
168If set to 2, the maximum amount of debug information is printed including
169all I/O requests.
170.El
171.Sh EXIT STATUS
172Exit status is 0 on success, and 1 if the command fails.
173.Sh EXAMPLES
174The following example shows how to create a transparent provider for disk
175.Pa /dev/da0
176with 50% write failure probability, and how to destroy it.
177.Bd -literal -offset indent
178gnop create -v -w 50 da0
179gnop destroy -v da0.nop
180.Ed
181.Pp
182The traffic statistics for the given transparent providers can be obtained
183with the
184.Cm list
185command.
186The example below shows the number of bytes written with
187.Xr newfs 8 :
188.Bd -literal -offset indent
189gnop create da0
190newfs /dev/da0.nop
191gnop list
192.Ed
193.Sh SEE ALSO
194.Xr geom 4 ,
195.Xr geom 8
196.Sh HISTORY
197The
198.Nm
199utility appeared in
200.Fx 5.3 .
201.Sh AUTHORS
202.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
203