| 1 | =head1 NAME |
| 2 | |
| 3 | kaserver - Initializes the Authentication Server |
| 4 | |
| 5 | =head1 SYNOPSIS |
| 6 | |
| 7 | =for html |
| 8 | <div class="synopsis"> |
| 9 | |
| 10 | B<kaserver> [B<-noAuth>] [B<-database> <I<dbpath>>] |
| 11 | S<<< [B<-auditlog> <I<log path>>] >>> |
| 12 | S<<< [B<-audit-interface> (file | sysvmq)] >>> |
| 13 | S<<< [B<-localfiles> <I<lclpath>>] >>> S<<< [B<-minhours> <I<n>>] >>> |
| 14 | S<<< [B<-servers> <I<serverlist>>] >>> [B<-enable_peer_stats>] |
| 15 | [B<-enable_process_stats>] [B<-rxbind>] [B<-crossrealm>] [B<-help>] |
| 16 | |
| 17 | =for html |
| 18 | </div> |
| 19 | |
| 20 | =head1 DESCRIPTION |
| 21 | |
| 22 | The B<kaserver> command initializes the Authentication Server, an obsolete |
| 23 | way of providing authentication services to an AFS cell. It should no |
| 24 | longer be used; instead, it should be replaced with a Kerberos version 5 |
| 25 | KDC. It is provided only for support of sites already running the |
| 26 | Authentication Server and that have not yet migrated to Kerberos version |
| 27 | 5. |
| 28 | |
| 29 | For a cell using the Authentication Server, it runs on every database |
| 30 | server machine. In the conventional configuration, its binary file is |
| 31 | located in the F</usr/afs/bin> directory on a file server machine. |
| 32 | |
| 33 | The B<kaserver> command is not normally issued at the command shell prompt |
| 34 | but rather placed into a file server machine's F</usr/afs/local/BosConfig> |
| 35 | file with the B<bos create> command. If it is ever issued at the command |
| 36 | shell prompt, the issuer must be logged onto a database server machine as |
| 37 | the local superuser C<root>. |
| 38 | |
| 39 | As it initializes, the Authentication Server process creates the two files |
| 40 | that constitute the Authentication Database, F<kaserver.DB0> and |
| 41 | F<kaserver.DBSYS1>, in the F</usr/afs/db> directory if they do not already |
| 42 | exist. Use the commands in the B<kas> suite to administer the database. |
| 43 | |
| 44 | The Authentication Server is responsible for several aspects of AFS |
| 45 | security, including: |
| 46 | |
| 47 | =over 4 |
| 48 | |
| 49 | =item * |
| 50 | |
| 51 | Maintenance of all AFS server encryption keys and user passwords in the |
| 52 | Authentication Database. |
| 53 | |
| 54 | =item * |
| 55 | |
| 56 | Creation of the tickets and tokens that users and servers use to establish |
| 57 | secure connections. Its Ticket Granting Service (TGS) component performs |
| 58 | this function. |
| 59 | |
| 60 | =back |
| 61 | |
| 62 | The Authentication Server records a trace of its activity in the |
| 63 | F</usr/afs/logs/AuthLog> file. Use the B<bos getlog> command to display |
| 64 | the contents of the file. Use the B<kdb> command to read the protected |
| 65 | files associated with the F<AuthLog> file, F<AuthLog.dir> and |
| 66 | F<AuthLog.pag>. |
| 67 | |
| 68 | This command does not use the syntax conventions of the AFS command |
| 69 | suites. Provide the command name and all option names in full. |
| 70 | |
| 71 | =head1 CAUTIONS |
| 72 | |
| 73 | The Authentication Server provides only Kerberos version 4, which is no |
| 74 | longer considered sufficiently secure. It can only use DES encryption for |
| 75 | user keys, is vulnerable to known flaws in the Kerberos version 4 |
| 76 | protocol, and is based on protocols that are obsolete and no longer |
| 77 | developed. The Authentication Server is also not widely tested and is |
| 78 | known to have problems on some platforms OpenAFS otherwise supports. |
| 79 | |
| 80 | The Authentication Server should not be used for any new deployment. It is |
| 81 | provided only for sites that need to use it while preparing for a |
| 82 | migration to Kerberos KDC. No significant updates to the Authentication |
| 83 | Server will be developed, and it will be removed from a future version of |
| 84 | OpenAFS. |
| 85 | |
| 86 | =head1 OPTIONS |
| 87 | |
| 88 | =over 4 |
| 89 | |
| 90 | =item B<-noAuth> |
| 91 | |
| 92 | Assigns the unprivileged identity C<anonymous> to the issuer. Thus, it |
| 93 | establishes an unauthenticated connection between the issuer and the |
| 94 | Authentication Server. It is useful only when authorization checking is |
| 95 | disabled on the database server machine. In normal circumstances, the |
| 96 | Authentication Server allows only authorized (privileged) users to issue |
| 97 | commands that affect or contact the Authentication Database and will |
| 98 | refuse to perform such an action even if the B<-noAuth> flag is used. |
| 99 | |
| 100 | =item B<-database> <I<dbpath>> |
| 101 | |
| 102 | Specifies the pathname of an alternate directory in which the |
| 103 | Authentication Database files reside. Provide the complete pathname, |
| 104 | ending in the base filename to which the C<.DB0> and C<.DBSYS1> extensions |
| 105 | are appended. For example, the appropriate value for the default database |
| 106 | files is F</usr/afs/db/kaserver>. |
| 107 | |
| 108 | Provide the B<-localfiles> argument along with this one; otherwise, the |
| 109 | B<-localfiles> argument is also set to the value of this argument, which |
| 110 | is probably inappropriate. |
| 111 | |
| 112 | =item B<-auditlog> <I<log path>> |
| 113 | |
| 114 | Turns on audit logging, and sets the path for the audit log. The audit |
| 115 | log records information about RPC calls, including the name of the RPC |
| 116 | call, the host that submitted the call, the authenticated entity (user) |
| 117 | that issued the call, the parameters for the call, and if the call |
| 118 | succeeded or failed. |
| 119 | |
| 120 | =item B<-audit-interface> (file | sysvmq) |
| 121 | |
| 122 | Specifies what audit interface to use. Defaults to C<file>. See |
| 123 | L<fileserver(8)> for an explanation of each interface. |
| 124 | |
| 125 | =item B<-localfiles> <I<lclpath>> |
| 126 | |
| 127 | Specifies the pathname of an alternate directory in which the auxiliary |
| 128 | Authentication Database file resides. Provide the complete pathname, |
| 129 | ending in the base filename to which the C<auxdb> suffix is appended. For |
| 130 | example, the appropriate value for the default auxiliary database file is |
| 131 | F</usr/afs/local/kaserver>. |
| 132 | |
| 133 | =item B<-minhours> <I<n>> |
| 134 | |
| 135 | Specifies the minimum number of hours that must pass between password |
| 136 | changes made by any regular user. System administrators (with the C<ADMIN> |
| 137 | flag in their Authentication Database entry) can change passwords as often |
| 138 | as desired. Setting a minimum time between password changes is not |
| 139 | recommended. |
| 140 | |
| 141 | =item B<-servers> <I<authentication servers>>+ |
| 142 | |
| 143 | Names each database server machine running an Authentication Server with |
| 144 | which the local Authentication Server is to synchronize its copy of the |
| 145 | Authentication Database, rather than with the machines listed in the local |
| 146 | F</usr/afs/etc/CellServDB> file. |
| 147 | |
| 148 | =item B<-enable_peer_stats> |
| 149 | |
| 150 | Activates the collection of Rx statistics and allocates memory for their |
| 151 | storage. For each connection with a specific UDP port on another machine, |
| 152 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and |
| 153 | so on) sent or received. To display or otherwise access the records, use |
| 154 | the Rx Monitoring API. |
| 155 | |
| 156 | =item B<-enable_process_stats> |
| 157 | |
| 158 | Activates the collection of Rx statistics and allocates memory for their |
| 159 | storage. A separate record is kept for each type of RPC (FetchFile, |
| 160 | GetStatus, and so on) sent or received, aggregated over all connections to |
| 161 | other machines. To display or otherwise access the records, use the Rx |
| 162 | Monitoring API. |
| 163 | |
| 164 | =item B<-rxbind> |
| 165 | |
| 166 | Bind the Rx socket to the primary interface only. (If not specified, the Rx |
| 167 | socket will listen on all interfaces.) |
| 168 | |
| 169 | =item B<-crossrealm> |
| 170 | |
| 171 | Enable cross-realm authentication. The use of this option is considered |
| 172 | insecure, and thus strongly discouraged. See OPENAFS-SA-2003-001. |
| 173 | |
| 174 | =item B<-help> |
| 175 | |
| 176 | Prints the online help for this command. All other valid options are |
| 177 | ignored. |
| 178 | |
| 179 | =back |
| 180 | |
| 181 | =head1 EXAMPLES |
| 182 | |
| 183 | The following B<bos create> command creates a C<kaserver> process on |
| 184 | C<fs3.example.com> (the command appears on two lines here only for |
| 185 | legibility): |
| 186 | |
| 187 | % bos create -server fs3.example.com -instance kaserver \ |
| 188 | -type simple -cmd /usr/afs/bin/kaserver |
| 189 | |
| 190 | =head1 PRIVILEGE REQUIRED |
| 191 | |
| 192 | The issuer must be logged in as the superuser C<root> on a file server |
| 193 | machine to issue the command at a command shell prompt. It is conventional |
| 194 | instead to create and start the process by issuing the B<bos create> |
| 195 | command. |
| 196 | |
| 197 | =head1 SEE ALSO |
| 198 | |
| 199 | L<AuthLog(5)>, |
| 200 | L<BosConfig(5)>, |
| 201 | L<CellServDB(5)>, |
| 202 | L<kaserver.DB0(5)>, |
| 203 | L<kaserverauxdb(5)>, |
| 204 | L<bos(8)>, |
| 205 | L<bos_create(8)>, |
| 206 | L<bos_getlog(8)>, |
| 207 | L<kas(8)>, |
| 208 | L<kdb(8)> |
| 209 | |
| 210 | =head1 COPYRIGHT |
| 211 | |
| 212 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. |
| 213 | |
| 214 | This documentation is covered by the IBM Public License Version 1.0. It was |
| 215 | converted from HTML to POD by software written by Chas Williams and Russ |
| 216 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |