Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | kas - Introduction to the kas command suite | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The commands in the B<kas> command suite are the administrative interface | |
8 | to the Authentication Server, an obsolete AFS server process that | |
9 | maintains the Authentication Database and provides the authentication | |
10 | tickets that client applications must present to AFS servers in order to | |
11 | obtain access to AFS data and other services. It is used only for cells | |
12 | still running the Authentication Server until they can migrate to a | |
13 | Kerberos version 5 KDC. | |
14 | ||
15 | There are several categories of commands in the B<kas> command suite: | |
16 | ||
17 | =over 4 | |
18 | ||
19 | =item * | |
20 | ||
21 | Commands to create, modify, examine and delete entries in the | |
22 | Authentication Database, including passwords: | |
23 | L<B<kas create>|kas_create(8)>, | |
24 | L<B<kas delete>|kas_delete(8)>, | |
25 | L<B<kas examine>|kas_examine(8)>, | |
26 | L<B<kas list>|kas_list(8)>, | |
27 | L<B<kas setfields>|kas_setfields(8)>, | |
28 | L<B<kas setkey>|kas_setkey(8)>, | |
29 | L<B<kas setpassword>|kas_setpassword(8)>, | |
30 | and L<B<kas unlock>|kas_unlock(8)>. | |
31 | ||
32 | =item * | |
33 | ||
34 | Commands to create, delete, and examine tokens and server tickets: | |
35 | L<B<kas forgetticket>|kas_forgetticket(8)>, | |
36 | L<B<kas listtickets>|kas_listtickets(8)>, | |
37 | L<B<kas noauthentication>|kas_noauthentication(8)>, | |
38 | and L<B<kas stringtokey>|kas_stringtokey(8)>. | |
39 | ||
40 | =item * | |
41 | ||
42 | A command to enter interactive mode: | |
43 | L<B<kas interactive>|kas_interactive(8)>. | |
44 | ||
45 | =item * | |
46 | ||
47 | A command to trace Authentication Server operations: | |
48 | L<B<kas statistics>|kas_statistics(8)>. | |
49 | ||
50 | =item * | |
51 | ||
52 | Commands to obtain help: | |
53 | L<B<kas apropos>|kas_apropos(8)> | |
54 | and L<B<kas help>|kas_help(8)>. | |
55 | ||
56 | =item * | |
57 | ||
58 | A command to display the OpenAFS command suite version: B<kas version>. | |
59 | ||
60 | =back | |
61 | ||
62 | Because of the sensitivity of information in the Authentication Database, | |
63 | the Authentication Server authenticates issuers of B<kas> commands | |
64 | directly, rather than accepting the standard token generated by the Ticket | |
65 | Granting Service. Any B<kas> command that requires administrative | |
66 | privilege prompts the issuer for a password. The resulting ticket is valid | |
67 | for six hours unless the maximum ticket lifetime for the issuer or the | |
68 | Authentication Server's Ticket Granting Service is shorter. | |
69 | ||
70 | To avoid having to provide a password repeatedly when issuing a sequence | |
71 | of B<kas> commands, enter I<interactive mode> by issuing the B<kas | |
72 | interactive> command, typing B<kas> without any operation code, or typing | |
73 | B<kas> followed by a user and cell name, separated by an at-sign (C<@>; an | |
74 | example is C<kas smith.admin@example.com>). After prompting once for a | |
75 | password, the Authentication Server accepts the resulting token for every | |
76 | command issued during the interactive session. See L<kas_interactive(8)> | |
77 | for a discussion of when to use each method for entering interactive mode | |
78 | and of the effects of entering a session. | |
79 | ||
80 | The Authentication Server maintains two databases on the local disk of the | |
81 | machine where it runs: | |
82 | ||
83 | =over 4 | |
84 | ||
85 | =item * | |
86 | ||
87 | The Authentication Database (F</usr/afs/db/kaserver.DB0>) stores the | |
88 | information used to provide AFS authentication services to users and | |
89 | servers, including the password scrambled as an encryption key. The | |
90 | reference page for the B<kas examine> command describes the information in | |
91 | a database entry. | |
92 | ||
93 | =item * | |
94 | ||
95 | An auxiliary file (F</usr/afs/local/kaauxdb> by default) that tracks how | |
96 | often the user has provided an incorrect password to the local | |
97 | Authentication Server. The reference page for the B<kas setfields> command | |
98 | describes how the Authentication Server uses this file to enforce the | |
99 | limit on consecutive authentication failures. To designate an alternate | |
100 | directory for the file, use the B<kaserver> command's B<-localfiles> | |
101 | argument. | |
102 | ||
103 | =back | |
104 | ||
105 | =head1 CAUTIONS | |
106 | ||
107 | The B<kas> command suite is provided only for administration of the | |
108 | obsolete Authentication Server for cells that have not yet migrated to a | |
109 | Kerberos version 5 KDC. New deployments should not use the Authentication | |
110 | Server, and it and the B<kas> command suite will be removed in a future | |
111 | version of OpenAFS. | |
112 | ||
113 | =head1 OPTIONS | |
114 | ||
115 | The following arguments and flags are available on many commands in the | |
116 | B<kas> suite. (Some of them are unavailable on commands entered in | |
117 | interactive mode, because the information they specify is established when | |
118 | entering interactive mode and cannot be changed except by leaving | |
119 | interactive mode.) The reference page for each command also lists them, | |
120 | but they are described here in greater detail. | |
121 | ||
122 | =over 4 | |
123 | ||
124 | =item B<-admin_username> <I<user name>> | |
125 | ||
126 | Specifies the user identity under which to authenticate with the | |
127 | Authentication Server for execution of the command. If this argument is | |
128 | omitted, the B<kas> command interpreter requests authentication for the | |
129 | identity under which the issuer is logged onto the local machine. Do not | |
130 | combine this argument with the B<-noauth> flag. | |
131 | ||
132 | =item B<-cell> <I<cell name>> | |
133 | ||
134 | Names the cell in which to run the command. It is acceptable to abbreviate | |
135 | the cell name to the shortest form that distinguishes it from the other | |
136 | entries in the F</usr/vice/etc/CellServDB> file on the local machine. If | |
137 | the B<-cell> argument is omitted, the command interpreter determines the | |
138 | name of the local cell by reading the following in order: | |
139 | ||
140 | =over 4 | |
141 | ||
142 | =item * | |
143 | ||
144 | The value of the AFSCELL environment variable. | |
145 | ||
146 | =item * | |
147 | ||
148 | The local F</usr/vice/etc/ThisCell> file. | |
149 | ||
150 | =back | |
151 | ||
152 | The B<-cell> argument is not available on commands issued in interactive | |
153 | mode. The cell defined when the B<kas> command interpreter enters | |
154 | interactive mode applies to all commands issued during the interactive | |
155 | session. | |
156 | ||
157 | =item B<-help> | |
158 | ||
159 | Prints a command's online help message on the standard output stream. Do | |
160 | not combine this flag with any of the command's other options; when it is | |
161 | provided, the command interpreter ignores all other options, and only | |
162 | prints the help message. | |
163 | ||
164 | =item B<-noauth> | |
165 | ||
166 | Establishes an unauthenticated connection to the Authentication Server, in | |
167 | which the Authentication Server treats the issuer as the unprivileged user | |
168 | C<anonymous>. It is useful only when authorization checking is disabled on | |
169 | the server machine (during the installation of a server machine or when | |
170 | the B<bos setauth> command has been used during other unusual | |
171 | circumstances). In normal circumstances, the Authentication Server allows | |
172 | only privileged users to issue most B<kas> commands, and refuses to | |
173 | perform such an action even if the B<-noauth> flag is provided. Do not | |
174 | combine this flag with the B<-admin_username> and B<-password_for_admin> | |
175 | arguments. | |
176 | ||
177 | =item B<-password_for_admin> <I<password>> | |
178 | ||
179 | Specifies the password of the command's issuer. It is best to omit this | |
180 | argument, which echoes the password visibly in the command shell, instead | |
181 | enter the password at the prompt. Do not combine this argument with the | |
182 | B<-noauth> flag. | |
183 | ||
184 | =item B<-servers> <I<machine name>>+ | |
185 | ||
186 | Establishes a connection with the Authentication Server running on each | |
187 | specified database server machine, instead of on each machine listed in | |
188 | the local F</usr/vice/etc/CellServDB> file. In either case, the B<kas> | |
189 | command interpreter then chooses one of the machines at random to contact | |
190 | for execution of each subsequent command. The issuer can abbreviate the | |
191 | machine name to the shortest form that allows the local name service to | |
192 | identify it uniquely. | |
193 | ||
194 | =back | |
195 | ||
196 | =head1 PRIVILEGE REQUIRED | |
197 | ||
198 | To issue most kas commands, the issuer must have the C<ADMIN> flag set in | |
199 | his or her Authentication Database entry (use the B<kas setfields> command | |
200 | to turn the flag on). | |
201 | ||
202 | =head1 SEE ALSO | |
203 | ||
204 | L<CellServDB(5)>, | |
205 | L<kaserver.DB0(5)>, | |
206 | L<kaserverauxdb(5)>, | |
207 | L<kas_apropos(8)>, | |
208 | L<kas_create(8)>, | |
209 | L<kas_delete(8)>, | |
210 | L<kas_examine(8)>, | |
211 | L<kas_forgetticket(8)>, | |
212 | L<kas_help(8)>, | |
213 | L<kas_interactive(8)>, | |
214 | L<kas_list(8)>, | |
215 | L<kas_listtickets(8)>, | |
216 | L<kas_noauthentication(8)>, | |
217 | L<kas_quit(8)>, | |
218 | L<kas_setfields(8)>, | |
219 | L<kas_setpassword(8)>, | |
220 | L<kas_statistics(8)>, | |
221 | L<kas_stringtokey(8)>, | |
222 | L<kas_unlock(8)>, | |
223 | L<kaserver(8)> | |
224 | ||
225 | =head1 COPYRIGHT | |
226 | ||
227 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
228 | ||
229 | This documentation is covered by the IBM Public License Version 1.0. It was | |
230 | converted from HTML to POD by software written by Chas Williams and Russ | |
231 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |