xref: /freebsd/sbin/ggate/ggatel/ggatel.8 (revision 119b75925c562202145d7bac7b676b98029c6cb9)
1.\" Copyright (c) 2004 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 14, 2015
28.Dt GGATEL 8
29.Os
30.Sh NAME
31.Nm ggatel
32.Nd "GEOM Gate local control utility"
33.Sh SYNOPSIS
34.Nm
35.Cm create
36.Op Fl v
37.Op Fl o Cm ro | wo | rw
38.Op Fl s Ar sectorsize
39.Op Fl t Ar timeout
40.Op Fl u Ar unit
41.Ar path
42.Nm
43.Cm destroy
44.Op Fl f
45.Fl u Ar unit
46.Nm
47.Cm list
48.Op Fl v
49.Op Fl u Ar unit
50.Nm
51.Cm rescue
52.Op Fl v
53.Op Fl o Cm ro | wo | rw
54.Fl u Ar unit
55.Ar path
56.Sh DESCRIPTION
57The
58.Nm
59utility is a local GEOM Gate class consumer.
60It can be used as a replacement for
61.Xr md 4
62devices or as a
63.Dq GEOMificator
64for non GEOM-aware devices, but it was mainly created as an example
65on how to use and how to communicate with the GEOM Gate kernel subsystem.
66.Pp
67Available commands:
68.Bl -tag -width ".Cm destroy"
69.It Cm create
70Create a
71.Nm ggate
72provider related to the given regular file or device.
73.It Cm destroy
74Destroy the given
75.Nm ggate
76provider.
77.It Cm list
78List
79.Nm ggate
80providers.
81.It Cm rescue
82Take over a previously created provider and handle pending and future
83requests. This is useful if the initial
84.Nm
85process died.
86To prevent data loss, the given path must lead to the
87regular file or device that was used to create the provider.
88.El
89.Pp
90Available options:
91.Bl -tag -width ".Fl s Cm ro | wo | rw"
92.It Fl f
93Forcibly destroy
94.Nm ggate
95provider (cancels all pending requests).
96.It Fl o Cm ro | wo | rw
97Specify permissions to use when opening the file or device: read-only
98.Pq Cm ro ,
99write-only
100.Pq Cm wo ,
101or read-write
102.Pq Cm rw .
103Default is
104.Cm rw .
105.It Fl s Ar sectorsize
106Sector size for
107.Nm ggate
108provider.
109If not specified, it is taken from the device, or set to 512 bytes for files.
110.It Fl t Ar timeout
111Number of seconds to wait before an I/O request will be canceled.
1120 means no timeout.
113Default is 30.
114.It Fl u Ar unit
115Unit number to use.
116.It Fl v
117Do not fork, run in foreground and print debug information on standard
118output.
119.It Ar path
120Path to a regular file or device.
121.El
122.Sh EXIT STATUS
123Exit status is 0 on success, or 1 if the command fails.
124To get details about the failure,
125.Nm
126should be called with the
127.Fl v
128option.
129.Sh EXAMPLES
130.Dq GEOMify
131the
132.Dq Li fd0
133device and use
134.Xr gbde 8
135to encrypt data on a floppy disk.
136.Bd -literal -offset indent
137ggatel create -u 5 /dev/fd0
138gbde init /dev/ggate5
139gbde attach ggate5
140newfs /dev/ggate5.bde
141mount /dev/ggate5.bde /secret
142cp /private/foo /secret/
143umount /secret
144gbde detach ggate5
145ggatel destroy -u 5
146.Ed
147.Sh SEE ALSO
148.Xr geom 4 ,
149.Xr gbde 8 ,
150.Xr ggatec 8 ,
151.Xr ggated 8 ,
152.Xr mount 8 ,
153.Xr newfs 8
154.Sh AUTHORS
155The
156.Nm
157utility as well as this manual page was written by
158.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org .
159