69c4dd3d649775f290f171b5f2ebb69067f69d92
[openafs.git] / 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 =back
98
99 =head1 CAUTIONS
100
101 The file dump format does not include supergroup information, so should
102 not be used if you have and are using groups within groups.
103
104 In all cases, entry timestamps and other information is also not
105 preserved.
106
107 The epoch and version are reported on standard error.  On little-endian
108 machines, they'll be byte swapped, so may be very random.
109
110 =head1 EXAMPLES
111
112 The following example shows how to initialize the database from scratch.
113
114 Before you do this, make sure B<ptserver> is not running.  If you have
115 multiple database servers, make sure F<prdb.*> does not exist on any
116 server machine.
117
118 Now, type this in EXACTLY, including the leading space on the line
119 indicated.  But do use Control-D at the end, not up-arrow D.
120
121     pt_util -w
122     admin 128/20 1 -204 -204
123     system:administrators 130/20 -204 -204 -204
124      admin 1
125     ^D
126
127 You will see this:
128
129     # pt_util -w
130     pt_util: /usr/afs/db/prdb.DB0: Bad UBIK_MAGIC. Is 0 should be 354545
131     Ubik Version is: 2.0
132     admin 128/20 1 -204 -204
133     system:administrators 130/20 -204 -204 -204
134     Error while creating system:administrators: Entry for id already exists
135      admin 1
136     pt_util: Ubik Version number changed during execution.
137     Old Version = 2.0, new version = 33554432.0
138     #
139
140 To make a complete copy of the database,
141
142     # pt_util -user -members -datafile /tmp/out
143
144 To load from the complete copy,
145
146     # pt_util -w -datafile /tmp/out
147
148 Don't do this until you read cautions, above.
149
150 =head1 PRIVILEGE REQUIRED
151
152 The issuer must be logged in as the superuser C<root> on a file server
153 machine to use B<pt_util>.
154
155 =head1 SEE ALSO
156
157 L<prdb.DB0(5)>,
158 L<ptserver(8)>
159
160 =head1 COPYRIGHT
161
162 The following copyright covers this documentation:
163
164 Copyright (c) 2005 The Regents of the University of Michigan.  ALL RIGHTS
165 RESERVED.
166
167 Permission is granted to use, copy, create derivative works and
168 redistribute this software and such derivative works for any purpose, so
169 long as the name of the University of Michigan is not used in any
170 advertising or publicity pertaining to the use or distribution of this
171 software without specific, written prior authorization.  If the above
172 copyright notice or any other identification of the University of Michigan
173 is included in any copy of any portion of this software, then the
174 disclaimer below must also be included.
175
176 This software is provided as is, without representation from the
177 University of Michigan as to its fitness for any purpose, and without
178 warranty by the University of Michigan of any kind, either express or
179 implied, including without limitation the implied warranties of
180 merchantability and fitness for a particular purpose.  The regents of the
181 University of Michigan shall not be liable for any damages, including
182 special, indirect, incidental, or consequential damages, with respect to
183 any claim arising out of or in connection with the use of the software,
184 even if it has been or is hereafter advised of the possibility of such
185 damages.
186
187 =cut