Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | ptserver - Initializes the Protection Server | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | ptserver S<<< [B<-database> | B<-db> <I<db path>>] >>> | |
11 | S<<< [B<-p> <I<number of threads>>] >>> | |
12 | S<<< [B<-d> <I<debug level>>] >>> | |
13 | S<<< [B<-groupdepth> | B<-depth> <I<# of nested groups>>] >>> | |
14 | S<<< [B<-default_access> <I<user access mask>> <I<group access mask>>] >>> | |
15 | [B<-restricted>] [B<-restrict_anonymous>] [B<-enable_peer_stats>] | |
16 | [B<-enable_process_stats>] [B<-allow-dotted-principals>] | |
17 | [B<-rxbind>] S<<< [B<-auditlog> <I<file path>>] >>> | |
18 | S<<< [B<-audit-interface> (file | sysvmq)] >>> | |
19 | S<<< [B<-syslog>[=<I<FACILITY>>]] >>> | |
20 | S<<< [B<-logfile> <I<log file>>] >>> | |
21 | [B<-transarc-logs>] | |
22 | S<<< [B<-config> <I<configuration path>>] >>> | |
23 | S<<< [B<-rxmaxmtu> <I<bytes>>] >>> | |
24 | [B<-help>] | |
25 | ||
26 | =for html | |
27 | </div> | |
28 | ||
29 | =head1 DESCRIPTION | |
30 | ||
31 | The B<ptserver> command initializes the Protection Server, which must run | |
32 | on every database server machine. In the conventional configuration, its | |
33 | binary file is located in the F</usr/afs/bin> directory on a file server | |
34 | machine. | |
35 | ||
36 | The ptserver command is not normally issued at the command shell prompt, | |
37 | but rather placed into a database server machine's | |
38 | F</usr/afs/local/BosConfig> file with the B<bos create> command. If it is | |
39 | ever issued at the command shell prompt, the issuer must be logged onto a | |
40 | file server machine as the local superuser C<root>. | |
41 | ||
42 | The Protection Server performs the following tasks: | |
43 | ||
44 | =over 4 | |
45 | ||
46 | =item * | |
47 | ||
48 | Maintains the Protection Database, which contains entries for every user | |
49 | and group in the cell. Use the B<pts> commands to administer the database. | |
50 | ||
51 | =item * | |
52 | ||
53 | Allocates AFS IDs for new user, machine and group entries and maps each ID | |
54 | to the corresponding name. | |
55 | ||
56 | =item * | |
57 | ||
58 | Generates a current protection subgroup (CPS) at the File Server's | |
59 | request. The CPS lists all groups to which a user or machine belongs. | |
60 | ||
61 | =back | |
62 | ||
63 | When using Kerberos 5, cross-realm authentication is possible. If the | |
64 | special pts group system:authuser@FOREIGN.REALM exists and its group quota | |
65 | is greater than zero, B<aklog> will automatically create an entry for the | |
66 | foreign user in the local PTS database and add the foreign user to the | |
67 | system:authuser@FOREIGN.REALM PTS group. Each time a foreign user is | |
68 | created in the local PTS database, the group quota for the | |
69 | system:authuser@FOREIGN.REALM PTS group is decremented by one. | |
70 | ||
71 | This command does not use the syntax conventions of the AFS command | |
72 | suites. Provide the command name and all option names in full. | |
73 | ||
74 | =head1 OPTIONS | |
75 | ||
76 | =over 4 | |
77 | ||
78 | =item B<-d> <I<debug level>> | |
79 | ||
80 | Sets the detail level for the debugging trace written to the | |
81 | F</usr/afs/logs/PtLog> file. Provide one of the following values, each | |
82 | of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>, | |
83 | and C<125>. | |
84 | ||
85 | =item B<-database> | B<-db> <I<db path>> | |
86 | ||
87 | Specifies the pathname of an alternate directory in which the Protection | |
88 | Database files reside. Provide the complete pathname, ending in the base | |
89 | filename to which the C<.DB0> and C<.DBSYS1> extensions are appended. For | |
90 | example, the appropriate value for the default database files is | |
91 | F</usr/afs/db/prdb>. | |
92 | ||
93 | =item B<-p> <I<number of threads>> | |
94 | ||
95 | Sets the number of server lightweight processes (LWPs or pthreads) to run. | |
96 | Provide a positive integer from the range C<3> to C<64>. The default | |
97 | value is C<3>. | |
98 | ||
99 | =item B<-groupdepth> | B<-depth> <I<# of nested groups>> | |
100 | ||
101 | Specifies the group depth for nested groups when B<ptserver> is compiled | |
102 | with the SUPERGROUPS option enabled. The default depth for nested groups | |
103 | is 5. | |
104 | ||
105 | =item B<-default_access> <I<user access>> <I<group access>> | |
106 | ||
107 | Specifies the default user and group privacy flags to apply to each | |
108 | entry. Provide a string of five characters, one for each of the | |
109 | permissions. See L<pts_examine(1)> or L<pts_setfields(1)> for more | |
110 | information on the flags. | |
111 | ||
112 | =item B<-restricted> | |
113 | ||
114 | Run the PT Server in restricted mode. While in restricted mode, only | |
115 | members of the system:administrators PTS group may make any PTS changes. | |
116 | ||
117 | =item B<-restrict_anonymous> | |
118 | ||
119 | Run the PT Server in restricted anonymous access mode. While in this mode, | |
120 | only authenticated users will be able to access the PTS database. | |
121 | ||
122 | =item B<-enable_peer_stats> | |
123 | ||
124 | Activates the collection of Rx statistics and allocates memory for their | |
125 | storage. For each connection with a specific UDP port on another machine, | |
126 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and | |
127 | so on) sent or received. To display or otherwise access the records, use | |
128 | the Rx Monitoring API. | |
129 | ||
130 | =item B<-enable_process_stats> | |
131 | ||
132 | Activates the collection of Rx statistics and allocates memory for their | |
133 | storage. A separate record is kept for each type of RPC (FetchFile, | |
134 | GetStatus, and so on) sent or received, aggregated over all connections to | |
135 | other machines. To display or otherwise access the records, use the Rx | |
136 | Monitoring API. | |
137 | ||
138 | =item B<-allow-dotted-principals> | |
139 | ||
140 | By default, the RXKAD security layer will disallow access by Kerberos | |
141 | principals with a dot in the first component of their name. This is to | |
142 | avoid the confusion where principals user/admin and user.admin are both | |
143 | mapped to the user.admin PTS entry. Sites whose Kerberos realms don't have | |
144 | these collisions between principal names may disable this check by | |
145 | starting the server with this option. | |
146 | ||
147 | =item B<-rxbind> | |
148 | ||
149 | Bind the Rx socket to the primary interface only. (If not specified, the | |
150 | Rx socket will listen on all interfaces.) | |
151 | ||
152 | =item B<-syslog>[=<I<syslog facility>>] | |
153 | ||
154 | Specifies that logging output should go to syslog instead of the normal | |
155 | log file. B<-syslog>=I<FACILITY> can be used to specify to which facility | |
156 | the log message should be sent. Logging message sent to syslog are tagged | |
157 | with the string "ptserver". | |
158 | ||
159 | =item B<-logfile> <I<log file>> | |
160 | ||
161 | Sets the file to use for server logging. If logfile is not specified, and | |
162 | no other logging options are supplied, this will be F</usr/afs/logs/PtLog>. | |
163 | Note that this option is intended for debugging and testing purposes. | |
164 | Changing the location of the log file from the command line may result | |
165 | in undesirable interactions with tools such as B<bos>. | |
166 | ||
167 | =item B<-transarc-logs> | |
168 | ||
169 | Use Transarc style logging features. Rename the log file | |
170 | F</usr/afs/logs/PtLog> to F</usr/afs/logs/PtLog.old> when the PT Server is | |
171 | restarted. This option is provided for compatibility with older versions. | |
172 | ||
173 | =item B<-config> <I<configuration directory>> | |
174 | ||
175 | Set the location of the configuration directory used to configure this | |
176 | service. In a typical configuration this will be F</usr/afs/etc> - this | |
177 | option allows the use of alternative configuration locations for testing | |
178 | purposes. | |
179 | ||
180 | =item B<-auditlog> <I<log path>> | |
181 | ||
182 | Turns on audit logging, and sets the path for the audit log. The audit | |
183 | log records information about RPC calls, including the name of the RPC | |
184 | call, the host that submitted the call, the authenticated entity (user) | |
185 | that issued the call, the parameters for the call, and if the call | |
186 | succeeded or failed. | |
187 | ||
188 | =item B<-audit-interface> (file | sysvmq) | |
189 | ||
190 | Specifies what audit interface to use. Defaults to C<file>. See | |
191 | L<fileserver(8)> for an explanation of each interface. | |
192 | ||
193 | =item B<-rxmaxmtu> <I<bytes>> | |
194 | ||
195 | Sets the maximum transmission unit for the RX protocol. | |
196 | ||
197 | =item B<-help> | |
198 | ||
199 | Prints the online help for this command. All other valid options are | |
200 | ignored. | |
201 | ||
202 | =back | |
203 | ||
204 | =head1 EXAMPLES | |
205 | ||
206 | The following B<bos create> command creates a C<ptserver> process on the | |
207 | machine C<fs3.example.com>. The command appears here on multiple lines only | |
208 | for legibility. | |
209 | ||
210 | % bos create -server fs3.example.com -instance ptserver \ | |
211 | -type simple -cmd /usr/afs/bin/ptserver | |
212 | ||
213 | =head1 PRIVILEGE REQUIRED | |
214 | ||
215 | The issuer must be logged in as the superuser C<root> on a file server | |
216 | machine to issue the command at a command shell prompt. It is conventional | |
217 | instead to create and start the process by issuing the B<bos create> | |
218 | command. | |
219 | ||
220 | =head1 SEE ALSO | |
221 | ||
222 | L<BosConfig(5)>, | |
223 | L<PtLog(5)>, | |
224 | L<prdb.DB0(5)>, | |
225 | L<bos_create(8)>, | |
226 | L<bos_getlog(8)>, | |
227 | L<pts(1)> | |
228 | ||
229 | =head1 COPYRIGHT | |
230 | ||
231 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
232 | ||
233 | This documentation is covered by the IBM Public License Version 1.0. It was | |
234 | converted from HTML to POD by software written by Chas Williams and Russ | |
235 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |