1.\" $NetBSD: iprop.8,v 1.7 2023/06/19 21:41:44 christos 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 transactions from 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 88is used to propagate changes to a Heimdal Kerberos database from the 89master Kerberos server on which it runs to slave Kerberos servers 90running 91.Nm ipropd-slave . 92.Pp 93The slaves are specified by the contents of the 94.Pa slaves 95file in the KDC's database directory, e.g.\& 96.Pa /var/heimdal/slaves . 97This has principals one per-line of the form 98.Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM 99where 100.Ar slave 101is the hostname of the slave server in the given 102.Ar REALM , 103e.g.\& 104.Dl iprop/kerberos-1.example.com@EXAMPLE.COM 105On a slave, the argument 106.Fa master 107specifies the hostname of the master server from which to receive updates. 108.Pp 109In contrast to 110.Xr hprop 8 , 111which sends the whole database to the slaves regularly, 112.Nm 113normally sends only the changes as they happen on the master. 114The master keeps track of all the changes by assigning a version 115number to every transaction to the database. 116The slaves know which was the latest version they saw, and in this 117way it can be determined if they are in sync or not. 118A log of all the transactions is kept on the master. 119When a slave is at an older version than the oldest one in the log, 120the whole database has to be sent. 121.Pp 122The log of transactions is also used to implement a two-phase commit 123(with roll-forward for recovery) method of updating the HDB. 124Transactions are first recorded in the log, then in the HDB, then 125the log is updated to mark the transaction as committed. 126.Pp 127The changes are propagated over a secure channel (on port 2121 by 128default). 129This should normally be defined as 130.Dq iprop/tcp 131in 132.Pa /etc/services 133or another source of the services database. 134The master and slaves 135must each have access to a keytab with keys for the 136.Nm iprop 137service principal on the local host. 138.Pp 139There is a keep-alive feature logged in the master's 140.Pa slave-stats 141file (e.g.\& 142.Pa /var/heimdal/slave-stats ) . 143.Pp 144Supported options for 145.Nm ipropd-master : 146.Bl -tag -width Ds 147.It Fl c Ar string , Fl Fl config-file= Ns Ar string 148.It Fl r Ar string , Fl Fl realm= Ns Ar string 149.It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec 150keytab to get authentication from 151.It Fl d Ar file , Fl Fl database= Ns Ar file 152Database (default per KDC) 153.It Fl Fl slave-stats-file= Ns Ar file 154file for slave status information 155.It Fl Fl time-missing= Ns Ar time 156time before slave is polled for presence (default 2 min) 157.It Fl Fl time-gone= Ns Ar time 158time of inactivity after which a slave is considered gone (default 5 min) 159.It Fl Fl detach 160detach from console 161.It Fl Fl version 162.It Fl Fl help 163.El 164.Pp 165Supported options for 166.Nm ipropd-slave : 167.Bl -tag -width Ds 168.It Fl c Ar string , Fl Fl config-file= Ns Ar string 169.It Fl r Ar string , Fl Fl realm= Ns Ar string 170.It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec 171keytab to get authentication from 172.It Fl Fl time-lost= Ns Ar time 173time before server is considered lost (default 5 min) 174.It Fl Fl detach 175detach from console 176.It Fl Fl version 177.It Fl Fl help 178.El 179Time arguments for the relevant options above may be specified in forms 180like 5 min, 300 s, or simply a number of seconds. 181.Sh FILES 182.Pa slaves , 183.Pa slave-stats 184in the database directory. 185.Pa ipropd-master.pid , 186.Pa ipropd-slave.pid 187in the database directory, or in the directory named by the 188.Ev HEIM_PIDFILE_DIR 189environment variable. 190.Sh SEE ALSO 191.Xr krb5.conf 5 , 192.Xr hprop 8 , 193.Xr hpropd 8 , 194.Xr iprop-log 8 , 195.Xr kdc 8 . 196