doc/man-pages/pod8/pt_util.pod

   1 =head1 NAME
   2
   3 pt_util - Load or dump a Protection Server database
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<pt_util>
  11    S<<< [B<-w>] >>> S<<< [B<-user>] >>> S<<< [B<-group>] >>>
  12    S<<< [B<-members>] >>> S<<< [B<-name>] >>> S<<< [B<-system>] >>>
  13    S<<< [B<-xtra>] >>> S<<< [B<-prdb> <I<prdb file>>] >>>
  14    S<<< [B<-datafile> <I<data file>>] >>> S<<< [B<-help>] >>>
  15
  16 =for html
  17 </div>
  18
  19 =head1 DESCRIPTION
  20
  21 The B<pt_util> command can be used to load or dump the protection
  22 database.  It should only be used when B<ptserver> is not running.
  23
  24 The most likely reason to use it is to initialize the protection database
  25 when bringing up a new cell.  The current syntax for this, presented
  26 below, needs improvement.  B<pt_util> can also be used when problems are
  27 suspected with the database.  It can be used to dump the database or
  28 portions thereof, in several different ways, and to reload it.
  29
  30 The textual representation of the database has the following form:
  31 For users,
  32
  33     name flags/quota viceid ownerid creatorid
  34
  35 For groups,
  36
  37     name flags/quota viceid ownerid creatorid
  38      a-username a-user-viceid
  39
  40 The second line is repeated for each member of the group.  When reading
  41 the database, membership is not reported unless B<-members> is also
  42 included.
  43
  44 =head1 OPTIONS
  45
  46 If you don't specify any options, the only thing you'll learn is the ubik
  47 database epoch and version.
  48
  49 =over 4
  50
  51 =item B<-w>
  52
  53 Write to the protection database instead of reading.  Only the file
  54 arguments make sense in combination with this argument.
  55
  56 =item B<-user>
  57
  58 When reading, display users.
  59
  60 =item B<-group>
  61
  62 When reading, display groups (but not necessarily members).
  63
  64 =item B<-members>
  65
  66 When reading, display groups and also group members.
  67
  68 =item B<-name>
  69
  70 When reading,
  71 follow name hashes, instead of id hashes.
  72 This may print different information if the database was corrupted.
  73 Otherwise, it should print exactly the same information, except
  74 in a different order.
  75
  76 =item B<-system>
  77
  78 When reading, display system data, or more precisely, do not display
  79 entries with a viced <= -32768 or >= +97537.
  80
  81 =item B<-xtra>
  82
  83 When reading, display extra users and groups, or more precisely, do not
  84 display entries that are in the range -32767...+97536 inclusive.
  85
  86 =item B<-prdb> <I<prdb file>>
  87
  88 Specifies the complete pathname of the file in which the Protection
  89 Database resides.  Provide the complete name, including the ending
  90 F<.DB0>.
  91
  92 =item B<-datafile> <I<data file>>
  93
  94 Specify the file to which to dump (or B<-w> from which to read) textual
  95 database records.
  96
  97 =item B<-help>
  98
  99 Prints the online help for this command. All other valid options are ignored.
 100
 101 =back
 102
 103 =head1 CAUTIONS
 104
 105 The file dump format does not include supergroup information, so should
 106 not be used if you have and are using groups within groups.
 107
 108 In all cases, entry timestamps and other information is also not
 109 preserved.
 110
 111 =head1 EXAMPLES
 112
 113 The following example shows how to initialize the database from scratch.
 114
 115 Before you do this, make sure B<ptserver> is not running.  If you have
 116 multiple database servers, make sure F<prdb.*> does not exist on any
 117 server machine.
 118
 119 Now, type this in EXACTLY, including the leading space on the line
 120 indicated.  But do use Control-D at the end, not up-arrow D.
 121
 122     pt_util -w
 123     admin 128/20 1 -204 -204
 124     system:administrators 130/20 -204 -204 -204
 125      admin 1
 126     ^D
 127
 128 You will see this:
 129
 130     # pt_util -w
 131     pt_util: /usr/afs/db/prdb.DB0: Bad UBIK_MAGIC. Is 0 should be 354545
 132     Ubik Version is: 2.0
 133     admin 128/20 1 -204 -204
 134     system:administrators 130/20 -204 -204 -204
 135     Error while creating system:administrators: Entry for id already exists
 136      admin 1
 137     pt_util: Ubik Version number changed during execution.
 138     Old Version = 2.0, new version = 33554432.0
 139     #
 140
 141 To make a complete copy of the database,
 142
 143     # pt_util -user -members -datafile /tmp/out
 144
 145 To load from the complete copy,
 146
 147     # pt_util -w -datafile /tmp/out
 148
 149 Don't do this until you read cautions, above.
 150
 151 =head1 PRIVILEGE REQUIRED
 152
 153 The issuer must be logged in as the superuser C<root> on a database server
 154 machine to use B<pt_util>.
 155
 156 =head1 SEE ALSO
 157
 158 L<prdb.DB0(5)>,
 159 L<ptserver(8)>
 160
 161 =head1 COPYRIGHT
 162
 163 The following copyright covers this documentation:
 164
 165 Copyright (c) 2005 The Regents of the University of Michigan.  ALL RIGHTS
 166 RESERVED.
 167
 168 Permission is granted to use, copy, create derivative works and
 169 redistribute this software and such derivative works for any purpose, so
 170 long as the name of the University of Michigan is not used in any
 171 advertising or publicity pertaining to the use or distribution of this
 172 software without specific, written prior authorization.  If the above
 173 copyright notice or any other identification of the University of Michigan
 174 is included in any copy of any portion of this software, then the
 175 disclaimer below must also be included.
 176
 177 This software is provided as is, without representation from the
 178 University of Michigan as to its fitness for any purpose, and without
 179 warranty by the University of Michigan of any kind, either express or
 180 implied, including without limitation the implied warranties of
 181 merchantability and fitness for a particular purpose.  The regents of the
 182 University of Michigan shall not be liable for any damages, including
 183 special, indirect, incidental, or consequential damages, with respect to
 184 any claim arising out of or in connection with the use of the software,
 185 even if it has been or is hereafter advised of the possibility of such
 186 damages.
 187
 188 =cut