libexec/ypxfr/ypxfr.8

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