crypto/external/bsd/heimdal/dist/lib/kadm5/iprop.8

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