sbin/ggate/ggatel/ggatel.8

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