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