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