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