doc/man-pages/pod8/kaserver.pod

   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.