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$ 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 NOTES 126The FreeBSD version of 127.Nm ypxfr 128has support for a special map transfer protocol which works in 129conjunction with the FreeBSD 130.Xr rpc.ypxfrd 8 131server. This protocol allows it to transfer raw map database files from 132the NIS master server and can be many times faster than the standard 133transfer method, particularly for very large NIS maps. The 134.Nm ypxfr 135command will check to see if the 136.Xr rpc.ypxfrd 8 137server is registered on the NIS master server and attempt to use 138it if it is present. If it isn't it will fall back to the standard 139transfer method, copying the map contents from 140.Xr ypserv 8 141and creating new maps instead. 142.Pp 143Note that while the FreeBSD ypxfrd protocol is conceptually similar 144to the SunOS ypxfrd protocol, FreeBSD's protocol is not compatible with 145Sun's, therefore it will not work with Sun's ypxfrd server. FreeBSD 146slave systems can still transfer maps from any non-FreeBSD NIS server, 147however they will only be able to take advantage of the faster protocol 148if the master server is also running FreeBSD. 149.Sh OPTIONS 150The following options and flags are supported by 151.Nm ypxfr : 152.Bl -tag -width flag 153.It Fl f 154Force a map transfer. Normally, 155.Nm ypxfr 156will not transfer a map if it determines that the NIS master's copy 157is not newer than the existing copy already on the local host: the 158.Fl f 159flag forces a transfer regardless of which server's version is more recent. 160.It Fl c 161Do not send a 'clear current map' request to the 162.Xr ypserv 8 163process running on the local host. This flag is normally used when 164invoking 165.Nm ypxfr 166manually on a machine that is not yet running 167.Xr ypserv 8 . 168Without this flag, failure to contact the local NIS server will cause 169.Nm ypxfr 170to abort the transfer. 171.It Fl d Ar target domain 172Specify a target domain other than the current NIS domain. 173.It Fl h Ar source host 174Specify the name of the host from which to copy the NIS maps. This option 175is used to insure that 176.Nm ypxfr 177only copies maps from the NIS master server. 178.It Fl s Ar source domain 179Specify the domain from which to transfer a map, in the event that 180the transfer is being done across two different NIS domains. 181.It Fl p Ar path 182Specify the top level directory containing the NIS maps. By 183default, this path is 184.Pa /var/yp . 185The 186.Fl p 187flag allows you to specify an alternate path should you wish to 188store your NIS maps in a different part of the filesystem. The 189NIS server, 190.Xr ypserv 8 , 191passes this flag to 192.Nm ypxfr 193if it too has been told to use an alternate path. 194.It Fl C Ar taskid program-number ipaddr port 195These options are used only when 196.Nm ypxfr 197is invoked by 198.Xr ypserv 8 199in response to a map transfer request initiated by 200.Xr yppush 8 . 201In this instance, 202.Nm ypxfr 203needs to 'callback' to the 204.Xr yppush 8 205process and interact with it, so 206.Xr yppush 8 207passes to it an IP address 208.Ar ipaddr , 209port number 210.Ar port , 211registered program number 212.Ar program-number 213and a transaction ID 214.Ar taskid 215that it can use to contact the waiting 216.Xr yppush 8 217process on the master server. 218.It Ar mapname 219The name of the map to transfer. 220.El 221.Sh FILES 222.Bl -tag -width Pa -compact 223.It Pa /var/yp/[domainname]/[maps] 224The NIS maps for a particular NIS domain. 225.El 226.Sh SEE ALSO 227.Xr yp 4 , 228.Xr yppush 8 , 229.Xr ypserv 8 230.Sh AUTHOR 231Bill Paul <wpaul@ctr.columbia.edu> 232