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 Heimdal
  37 .Sh NAME
  38 .Nm iprop ,
  39 .Nm ipropd-master ,
  40 .Nm ipropd-slave
  41 .Nd propagate changes to 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 change 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 changes 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 changes are propagated over a secure channel (on port 2121 by
 121 default).
 122 This should normally be defined as
 123 .Dq iprop/tcp
 124 in
 125 .Pa /etc/services
 126 or another source of the services database.
 127 The master and slaves
 128 must each have access to a keytab with keys for the
 129 .Nm iprop
 130 service principal on the local host.
 131 .Pp
 132 There is a keep-alive feature logged in the master's
 133 .Pa slave-stats
 134 file (e.g.\&
 135 .Pa /var/heimdal/slave-stats ) .
 136 .Pp
 137 Supported options for
 138 .Nm ipropd-master :
 139 .Bl -tag -width Ds
 140 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 141 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 142 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 143 keytab to get authentication from
 144 .It Fl d Ar file , Fl Fl database= Ns Ar file
 145 Database (default per KDC)
 146 .It Fl Fl slave-stats-file= Ns Ar file
 147 file for slave status information
 148 .It Fl Fl time-missing= Ns Ar time
 149 time before slave is polled for presence (default 2 min)
 150 .It Fl Fl time-gone= Ns Ar time
 151 time of inactivity after which a slave is considered gone (default 5 min)
 152 .It Fl Fl detach
 153 detach from console
 154 .It Fl Fl version
 155 .It Fl Fl help
 156 .El
 157 .Pp
 158 Supported options for
 159 .Nm ipropd-slave :
 160 .Bl -tag -width Ds
 161 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 162 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 163 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 164 keytab to get authentication from
 165 .It Fl Fl time-lost= Ns Ar time
 166 time before server is considered lost (default 5 min)
 167 .It Fl Fl detach
 168 detach from console
 169 .It Fl Fl version
 170 .It Fl Fl help
 171 .El
 172 Time arguments for the relevant options above may be specified in forms
 173 like 5 min, 300 s, or simply a number of seconds.
 174 .Sh FILES
 175 .Pa slaves ,
 176 .Pa slave-stats
 177 in the database directory.
 178 .Sh SEE ALSO
 179 .Xr krb5.conf 5 ,
 180 .Xr hprop 8 ,
 181 .Xr hpropd 8 ,
 182 .Xr iprop-log 8 ,
 183 .Xr kdc 8 .