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.\" $FreeBSD$ 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 /usr/libexec/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 50The 51.Nm 52utility copies an 53.Tn NIS 54database (or 55.Pa map ) 56from one 57.Tn NIS 58server to another using 59.Tn NIS 60services. 61In 62.Fx , 63.Nm 64is generally invoked by 65.Xr ypserv 8 66when it receives a map transfer request from 67.Xr yppush 8 . 68The 69.Nm 70utility is used primarily in environments where several 71.Tn NIS 72servers are in use in a single domain. 73One server, the 74.Tn NIS 75master, maintains 76the canonical copies of all 77.Tn NIS 78maps, and all the other servers, 79the 80.Tn NIS 81slaves, copy new versions of the maps from the master whenever 82any updates are made (i.e., when a user updates their password via 83.Xr yppasswd 1 ) . 84.Pp 85When run, 86.Nm 87creates a temporary database file in 88.Pa /var/yp/[domainname] , 89and fills it with the contents of 90.Ar mapname 91as supplied by the specified 92.Ar source host . 93When the entire map has been transferred, 94.Nm 95deletes the original copy of 96.Ar mapname 97and moves the temporary copy into its place. 98When the transfer is 99complete, 100.Nm 101will attempt to send a 'clear current map' request to the local 102.Xr ypserv 8 103process to clear any possible references it may still have to the 104stale map. 105.Pp 106Note that all files created by 107.Nm 108are owner readable and writable only for security reasons. 109Since the 110.Tn NIS 111maps and the directory in which they reside are normally owned by 112root, this prevents non-privileged users from making unauthorized 113modifications. 114.Pp 115In order to maintain consistency across all 116.Tn NIS 117servers, 118.Nm 119can be run periodically in a 120.Xr cron 8 121job. 122Maps which change infrequently 123need only be updated once a day (preferably late at night when system 124usage is lowest), whereas those that are subject to frequent changes 125(such a 126.Pa passwd.byname 127and 128.Pa passwd.byuid ) 129should be updated perhaps once every hour. 130Using 131.Xr cron 8 132to automatically 133update the 134.Tn NIS 135maps is not strictly mandatory since all updates should 136be propagated by 137.Xr yppush 8 138when 139.Pa /var/yp/Makefile 140is run on the 141.Tn NIS 142master server, however it is good practice 143on large networks where possible outages could cause 144.Tn NIS 145servers to fall out of sync with each other. 146.Pp 147When 148.Nm 149is invoked without a controlling terminal, e.g.\& from inside 150.Xr ypserv 8 , 151it logs all its output using the 152.Xr syslog 3 153facility. 154.Sh NOTES 155The 156.Fx 157version of 158.Nm 159has support for a special map transfer protocol which works in 160conjunction with the 161.Fx 162.Xr rpc.ypxfrd 8 163server. 164This protocol allows it to transfer raw map database files from 165the 166.Tn NIS 167master server and can be many times faster than the standard 168transfer method, particularly for very large 169.Tn NIS 170maps. 171The 172.Nm 173utility will check to see if the 174.Xr rpc.ypxfrd 8 175server is registered on the 176.Tn NIS 177master server and attempt to use 178it if it is present. 179If it is not it will fall back to the standard 180transfer method, copying the map contents from 181.Xr ypserv 8 182and creating new maps instead. 183.Pp 184Note that while the 185.Fx 186ypxfrd protocol is conceptually similar 187to the SunOS ypxfrd protocol, 188the 189.Fx 190protocol is not compatible with 191Sun's, therefore it will not work with Sun's ypxfrd server. 192.Fx 193slave systems can still transfer maps from any 194.No non- Ns Fx 195.Tn NIS 196server, 197however they will only be able to take advantage of the faster protocol 198if the master server is also running 199.Fx . 200.Sh OPTIONS 201The following options and flags are supported by 202.Nm : 203.Bl -tag -width indent 204.It Fl f 205Force a map transfer. 206Normally, 207.Nm 208will not transfer a map if it determines that the 209.Tn NIS 210master's copy 211is not newer than the existing copy already on the local host: the 212.Fl f 213flag forces a transfer regardless of which server's version is more recent. 214.It Fl c 215Do not send a 'clear current map' request to the 216.Xr ypserv 8 217process running on the local host. 218This flag is normally used when 219invoking 220.Nm 221manually on a machine that is not yet running 222.Xr ypserv 8 . 223Without this flag, failure to contact the local 224.Tn NIS 225server will cause 226.Nm 227to abort the transfer. 228.It Fl d Ar target domain 229Specify a target domain other than the current 230.Tn NIS 231domain. 232.It Fl h Ar source host 233Specify the name of the host from which to copy the 234.Tn NIS 235maps. 236This option 237is used to ensure that 238.Nm 239only copies maps from the 240.Tn NIS 241master server. 242.It Fl s Ar source domain 243Specify the domain from which to transfer a map, in the event that 244the transfer is being done across two different 245.Tn NIS 246domains. 247.It Fl p Ar path 248Specify the top level directory containing the 249.Tn NIS 250maps. 251By 252default, this path is 253.Pa /var/yp . 254The 255.Fl p 256flag allows you to specify an alternate path should you wish to 257store your 258.Tn NIS 259maps in a different part of the file system. 260The 261.Tn NIS 262server, 263.Xr ypserv 8 , 264passes this flag to 265.Nm 266if it too has been told to use an alternate path. 267.It Fl C Ar taskid program-number ipaddr port 268These options are used only when 269.Nm 270is invoked by 271.Xr ypserv 8 272in response to a map transfer request initiated by 273.Xr yppush 8 . 274In this instance, 275.Nm 276needs to 'callback' to the 277.Xr yppush 8 278process and interact with it, so 279.Xr yppush 8 280passes to it an IP address 281.Ar ipaddr , 282port number 283.Ar port , 284registered program number 285.Ar program-number 286and a transaction ID 287.Ar taskid 288that it can use to contact the waiting 289.Xr yppush 8 290process on the master server. 291.It Ar mapname 292The name of the map to transfer. 293.El 294.Sh FILES 295.Bl -tag -width Pa -compact 296.It Pa /var/yp/[domainname]/[maps] 297The 298.Tn NIS 299maps for a particular 300.Tn NIS 301domain. 302.El 303.Sh SEE ALSO 304.Xr yp 8 , 305.Xr yppush 8 , 306.Xr ypserv 8 307.Sh AUTHORS 308.An Bill Paul Aq wpaul@ctr.columbia.edu 309