lib/kadm5/iprop.8

   1 .\" $Id$
   2 .\"
   3 .\" Copyright (c) 2005 Kungliga Tekniska Högskolan
   4 .\" (Royal Institute of Technology, Stockholm, Sweden).
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" 3. Neither the name of the Institute nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd May 24, 2005
  35 .Dt IPROP 8
  36 .Os
  37 .Sh NAME
  38 .Nm iprop ,
  39 .Nm ipropd-master ,
  40 .Nm ipropd-slave
  41 .Nd propagate transactions from a Heimdal Kerberos master KDC to slave KDCs
  42 .Sh SYNOPSIS
  43 .Nm ipropd-master
  44 .Oo Fl c Ar string \*(Ba Xo
  45 .Fl Fl config-file= Ns Ar string
  46 .Xc
  47 .Oc
  48 .Oo Fl r Ar string \*(Ba Xo
  49 .Fl Fl realm= Ns Ar string
  50 .Xc
  51 .Oc
  52 .Oo Fl k Ar kspec \*(Ba Xo
  53 .Fl Fl keytab= Ns Ar kspec
  54 .Xc
  55 .Oc
  56 .Oo Fl d Ar file \*(Ba Xo
  57 .Fl Fl database= Ns Ar file
  58 .Xc
  59 .Oc
  60 .Op Fl Fl slave-stats-file= Ns Ar file
  61 .Op Fl Fl time-missing= Ns Ar time
  62 .Op Fl Fl time-gone= Ns Ar time
  63 .Op Fl Fl detach
  64 .Op Fl Fl version
  65 .Op Fl Fl help
  66 .Nm ipropd-slave
  67 .Oo Fl c Ar string \*(Ba Xo
  68 .Fl Fl config-file= Ns Ar string
  69 .Xc
  70 .Oc
  71 .Oo Fl r Ar string \*(Ba Xo
  72 .Fl Fl realm= Ns Ar string
  73 .Xc
  74 .Oc
  75 .Oo Fl k Ar kspec \*(Ba Xo
  76 .Fl Fl keytab= Ns Ar kspec
  77 .Xc
  78 .Oc
  79 .Op Fl Fl time-lost= Ns Ar time
  80 .Op Fl Fl detach
  81 .Op Fl Fl version
  82 .Op Fl Fl help
  83 .Ar master
  84 .Sh DESCRIPTION
  85 .Nm ipropd-master
  86 is used to propagate changes to a Heimdal Kerberos database from the
  87 master Kerberos server on which it runs to slave Kerberos servers
  88 running
  89 .Nm ipropd-slave .
  90 .Pp
  91 The slaves are specified by the contents of the
  92 .Pa slaves
  93 file in the KDC's database directory, e.g.\&
  94 .Pa /var/heimdal/slaves .
  95 This has principals one per-line of the form
  96 .Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM
  97 where
  98 .Ar slave
  99 is the hostname of the slave server in the given
 100 .Ar REALM ,
 101 e.g.\&
 102 .Dl iprop/kerberos-1.example.com@EXAMPLE.COM
 103 On a slave, the argument
 104 .Fa master
 105 specifies the hostname of the master server from which to receive updates.
 106 .Pp
 107 In contrast to
 108 .Xr hprop 8 ,
 109 which sends the whole database to the slaves regularly,
 110 .Nm
 111 normally sends only the changes as they happen on the master.
 112 The master keeps track of all the changes by assigning a version
 113 number to every transaction to the database.
 114 The slaves know which was the latest version they saw, and in this
 115 way it can be determined if they are in sync or not.
 116 A log of all the transactions is kept on the master.
 117 When a slave is at an older version than the oldest one in the log,
 118 the whole database has to be sent.
 119 .Pp
 120 The log of transactions is also used to implement a two-phase commit
 121 (with roll-forward for recovery) method of updating the HDB.
 122 Transactions are first recorded in the log, then in the HDB, then
 123 the log is updated to mark the transaction as committed.
 124 .Pp
 125 The changes are propagated over a secure channel (on port 2121 by
 126 default).
 127 This should normally be defined as
 128 .Dq iprop/tcp
 129 in
 130 .Pa /etc/services
 131 or another source of the services database.
 132 The master and slaves
 133 must each have access to a keytab with keys for the
 134 .Nm iprop
 135 service principal on the local host.
 136 .Pp
 137 There is a keep-alive feature logged in the master's
 138 .Pa slave-stats
 139 file (e.g.\&
 140 .Pa /var/heimdal/slave-stats ) .
 141 .Pp
 142 Supported options for
 143 .Nm ipropd-master :
 144 .Bl -tag -width Ds
 145 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 146 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 147 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 148 keytab to get authentication from
 149 .It Fl d Ar file , Fl Fl database= Ns Ar file
 150 Database (default per KDC)
 151 .It Fl Fl slave-stats-file= Ns Ar file
 152 file for slave status information
 153 .It Fl Fl time-missing= Ns Ar time
 154 time before slave is polled for presence (default 2 min)
 155 .It Fl Fl time-gone= Ns Ar time
 156 time of inactivity after which a slave is considered gone (default 5 min)
 157 .It Fl Fl detach
 158 detach from console
 159 .It Fl Fl version
 160 .It Fl Fl help
 161 .El
 162 .Pp
 163 Supported options for
 164 .Nm ipropd-slave :
 165 .Bl -tag -width Ds
 166 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 167 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 168 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 169 keytab to get authentication from
 170 .It Fl Fl time-lost= Ns Ar time
 171 time before server is considered lost (default 5 min)
 172 .It Fl Fl detach
 173 detach from console
 174 .It Fl Fl version
 175 .It Fl Fl help
 176 .El
 177 Time arguments for the relevant options above may be specified in forms
 178 like 5 min, 300 s, or simply a number of seconds.
 179 .Sh FILES
 180 .Pa slaves ,
 181 .Pa slave-stats
 182 in the database directory.
 183 .Pa ipropd-master.pid ,
 184 .Pa ipropd-slave.pid
 185 in the database directory, or in the directory named by the
 186 .Ev HEIM_PIDFILE_DIR
 187 environment variable.
 188 .Sh SEE ALSO
 189 .Xr krb5.conf 5 ,
 190 .Xr hprop 8 ,
 191 .Xr hpropd 8 ,
 192 .Xr iprop-log 8 ,
 193 .Xr kdc 8 .