1.\" Copyright (c) 1995 2.\" Bill Paul <wpaul@ctr.columbia.edu>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by Bill Paul. 15.\" 4. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $Id: ypxfr.8,v 1.1.1.1 1995/12/25 03:07:13 wpaul Exp $ 32.\" 33.Dd February 5, 1995 34.Dt YPXFR 8 35.Os 36.Sh NAME 37.Nm ypxfr 38.Nd "transfer NIS database from remote server to local host" 39.Sh SYNOPSIS 40.Nm ypxfr 41.Op Fl f 42.Op Fl c 43.Op Fl d Ar target domain 44.Op Fl h Ar source host 45.Op Fl s Ar source domain 46.Op Fl p Ar path 47.Op Fl C Ar taskid program-number ipaddr port 48.Ar mapname 49.Sh DESCRIPTION 50.Nm ypxfr 51copies an NIS database (or 52.Pa map ) 53from one NIS server to another using NIS services. In FreeBSD, 54.Nm ypxfr 55is generally invoked by 56.Xr ypserv 8 57when it receives a map transfer request from 58.Xr yppush 8 . 59.Nm ypxfr 60is used primarily in environments where several NIS servers 61are in use in a single domain. One server, the NIS master, maintains 62the canonical copies of all NIS maps, and all the other servers, 63the NIS slaves, copy new versions of the maps from the master whenever 64any updates are made (i.e. when a user updates their password via 65.Xr yppasswd 1 66). 67.Pp 68When run, 69.Nm ypxfr 70creates a temporary database file in 71.Pa /var/yp/[domainmame] , 72and fills it with the contents of 73.Ar mapname 74as supplied by the specified 75.Ar source host . 76When the entire map has been transfered, 77.Nm ypxfr 78deletes the original copy of 79.Ar mapname 80and moves the temporary copy into its place. When the transfer is 81complete, 82.Nm ypxfr 83will attempt to send a 'clear current map' request to the local 84.Xr ypserv 8 85process to clear any possible references it may still have to the 86stale map. 87.Pp 88Note that all files created by 89.Nm ypxfr 90are owner readable and writable only for security reasons. Since the 91NIS maps and the directory in which they reside are normally owned by 92root, this prevents non-privleged users from making unauthorized 93modifications. 94.Pp 95In order to maintain consistency across all NIS servers, 96.Nm ypxfr 97can be run periodically in a 98.Xr cron 8 99job. Maps which change infrequently 100need only be updated once a day (preferably late at night when system 101usage is lowest), whereas those that are subject to frequent changes 102(such a 103.Pa passwd.byname 104and 105.Pa passwd.byuid ) 106should be updated perhaps once every hour. Using 107.Xr cron 8 108to automatically 109update the NIS maps is not strictly mandatory since all updates should 110be propagated by 111.Xr yppush 8 112when 113.Pa /var/yp/Makefile 114is run on the NIS master server, however it is good practice 115on large networks where possible outages could cause NIS servers to 116fall out of sync with each other. 117.Pp 118When 119.Nm ypxfr 120is invoked without a controlling terminal, e.g. from inside 121.Xr ypserv 8 , 122it logs all its output using the 123.Xr syslog 3 124facility. 125.Sh OPTIONS 126The following options and flags are supported by 127.Nm ypxfr : 128.Bl -tag -width flag 129.It Fl f 130Force a map transfer. Normally, 131.Nm ypxfr 132will not transfer a map if it determines that the NIS master's copy 133is not newer than the existing copy already on the local host: the 134.Fl f 135flag forces a transfer regardless of which server's version is more recent. 136.It Fl c 137Do not send a 'clear current map' request to the 138.Xr ypserv 8 139process running on the local host. This flag is normally used when 140invoking 141.Nm ypxfr 142manually on a machine that is not yet running 143.Xr ypserv 8 . 144Without this flag, failure to contact the local NIS server will cause 145.Nm ypxfr 146to abort the transfer. 147.It Fl d Ar target domain 148Specify a target domain other than the current NIS domain. 149.It Fl h Ar source host 150Specify the name of the host from which to copy the NIS maps. This option 151is used to insure that 152.Nm ypxfr 153only copies maps from the NIS master server. 154.It Fl s Ar source domain 155Specify the domain from which to transfer a map, in the event that 156the transfer is being done across two different NIS domains. 157.It Fl p Ar path 158Specify the top level directory containing the NIS maps. By 159default, this path is 160.Pa /var/yp . 161The 162.Fl p 163flag allows you to specify an alternate path should you wish to 164store your NIS maps in a different part of the filesystem. The 165NIS server, 166.Xr ypserv 8 , 167passes this flag to 168.Nm ypxfr 169if it too has been told to use an alternate path. 170.It Fl C Ar taskid program-number ipaddr port 171These options are used only when 172.Nm ypxfr 173is invoked by 174.Xr ypserv 8 175in response to a map transfer request initiated by 176.Xr yppush 8 . 177In this instance, 178.Nm ypxfr 179needs to 'callback' to the 180.Xr yppush 8 181process and interact with it, so 182.Xr yppush 8 183passes to it an IP address 184.Ar ipaddr , 185port number 186.Ar port , 187registered program number 188.Ar program-number 189and a transaction ID 190.Ar taskid 191that it can use to contact the waiting 192.Xr yppush 8 193process on the master server. 194.It Ar mapname 195The name of the map to transfer. 196.El 197.Sh FILES 198.Bl -tag -width Pa -compact 199.It Pa /var/yp/[domainname]/[maps] 200The NIS maps for a particular NIS domain. 201.El 202.Sh SEE ALSO 203.Xr yp 4 , 204.Xr ypserv 8 , 205.Xr yppush 8 206.Sh AUTHOR 207Bill Paul <wpaul@ctr.columbia.edu> 208