sbin/geom/class/shsec/gshsec.8

   1 .\" Copyright (c) 2005 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 October 1, 2013
  28 .Dt GSHSEC 8
  29 .Os
  30 .Sh NAME
  31 .Nm gshsec
  32 .Nd "control utility for shared secret devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl hv
  37 .Ar name
  38 .Ar prov prov ...
  39 .Nm
  40 .Cm stop
  41 .Op Fl fv
  42 .Ar name ...
  43 .Nm
  44 .Cm clear
  45 .Op Fl v
  46 .Ar prov ...
  47 .Nm
  48 .Cm dump
  49 .Ar prov ...
  50 .Nm
  51 .Cm list
  52 .Nm
  53 .Cm status
  54 .Nm
  55 .Cm load
  56 .Nm
  57 .Cm unload
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 utility is used for setting up a device which contains a shared secret.
  62 The secret is shared between the given providers.
  63 To collect the secret, all providers are needed.
  64 If one of the components is missing, there is no way to get any useful data from
  65 the rest of them.
  66 The first argument to
  67 .Nm
  68 indicates an action to be performed:
  69 .Bl -tag -width ".Cm destroy"
  70 .It Cm label
  71 Set up a shared secret device from the given components with the specified
  72 .Ar name .
  73 Metadata are stored in the last sector of every component.
  74 .It Cm stop
  75 Turn off an existing shared secret device by its
  76 .Ar name .
  77 This command does not touch on-disk metadata!
  78 .It Cm clear
  79 Clear metadata on the given providers.
  80 .It Cm dump
  81 Dump metadata stored on the given providers.
  82 .It Cm list
  83 See
  84 .Xr geom 8 .
  85 .It Cm status
  86 See
  87 .Xr geom 8 .
  88 .It Cm load
  89 See
  90 .Xr geom 8 .
  91 .It Cm unload
  92 See
  93 .Xr geom 8 .
  94 .El
  95 .Pp
  96 Additional options:
  97 .Bl -tag -width ".Fl f"
  98 .It Fl f
  99 Force the removal of the specified shared secret device.
 100 .It Fl h
 101 Hardcode providers' names in metadata.
 102 .It Fl v
 103 Be more verbose.
 104 .El
 105 .Sh EXIT STATUS
 106 Exit status is 0 on success, and 1 if the command fails.
 107 .Sh EXAMPLES
 108 The following example shows how to create a shared secret device.
 109 The secret will be split between a slice on a local disk and a USB Pen drive.
 110 .Bd -literal -offset indent
 111 gshsec label -v secret /dev/ada0s1 /dev/da0
 112 newfs /dev/shsec/secret
 113 .Ed
 114 .Pp
 115 From now on, when the USB Pen drive is inserted, it will be automatically
 116 detected and connected, making the secret available via the
 117 .Pa /dev/shsec/secret
 118 device.
 119 .Sh SEE ALSO
 120 .Xr geom 4 ,
 121 .Xr gbde 8 ,
 122 .Xr geom 8 ,
 123 .Xr newfs 8
 124 .Sh HISTORY
 125 The
 126 .Nm
 127 utility appeared in
 128 .Fx 5.4 .
 129 .Sh AUTHORS
 130 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org