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 .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 .Bx Free ,
  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/[domainmame] ,
  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 transfered,
  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-privleged 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 .Bx Free
 149 version of
 150 .Nm
 151 has support for a special map transfer protocol which works in
 152 conjunction with the
 153 .Bx Free
 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 .Bx Free
 175 ypxfrd protocol is conceptually similar
 176 to the SunOS ypxfrd protocol,
 177 .Bx Free Ns 's
 178 protocol is not compatible with
 179 Sun's, therefore it will not work with Sun's ypxfrd server.
 180 .Bx Free
 181 slave systems can still transfer maps from any
 182 .Bx non-Free
 183 .Tn NIS
 184 server,
 185 however they will only be able to take advantage of the faster protocol
 186 if the master server is also running
 187 .Bx Free .
 188 .Sh OPTIONS
 189 The following options and flags are supported by
 190 .Nm Ns :
 191 .Bl -tag -width indent
 192 .It Fl f
 193 Force a map transfer. Normally,
 194 .Nm
 195 will not transfer a map if it determines that the
 196 .Tn NIS
 197 master's copy
 198 is not newer than the existing copy already on the local host: the
 199 .Fl f
 200 flag forces a transfer regardless of which server's version is more recent.
 201 .It Fl c
 202 Do not send a 'clear current map' request to the
 203 .Xr ypserv 8
 204 process running on the local host. This flag is normally used when
 205 invoking
 206 .Nm
 207 manually on a machine that is not yet running
 208 .Xr ypserv 8 .
 209 Without this flag, failure to contact the local
 210 .Tn NIS
 211 server will cause
 212 .Nm
 213 to abort the transfer.
 214 .It Fl d Ar target domain
 215 Specify a target domain other than the current
 216 .Tn NIS
 217 domain.
 218 .It Fl h Ar source host
 219 Specify the name of the host from which to copy the
 220 .Tn NIS
 221 maps. This option
 222 is used to insure that
 223 .Nm
 224 only copies maps from the
 225 .Tn NIS
 226 master server.
 227 .It Fl s Ar source domain
 228 Specify the domain from which to transfer a map, in the event that
 229 the transfer is being done across two different
 230 .Tn NIS
 231 domains.
 232 .It Fl p Ar path
 233 Specify the top level directory containing the
 234 .Tn NIS
 235 maps. By
 236 default, this path is
 237 .Pa /var/yp .
 238 The
 239 .Fl p
 240 flag allows you to specify an alternate path should you wish to
 241 store your
 242 .Tn NIS
 243 maps in a different part of the filesystem. The
 244 .Tn NIS
 245 server,
 246 .Xr ypserv 8 ,
 247 passes this flag to
 248 .Nm
 249 if it too has been told to use an alternate path.
 250 .It Fl C Ar taskid program-number ipaddr port
 251 These options are used only when
 252 .Nm
 253 is invoked by
 254 .Xr ypserv 8
 255 in response to a map transfer request initiated by
 256 .Xr yppush 8 .
 257 In this instance,
 258 .Nm
 259 needs to 'callback' to the
 260 .Xr yppush 8
 261 process and interact with it, so
 262 .Xr yppush 8
 263 passes to it an IP address
 264 .Ar ipaddr ,
 265 port number
 266 .Ar port ,
 267 registered program number
 268 .Ar program-number
 269 and a transaction ID
 270 .Ar taskid
 271 that it can use to contact the waiting
 272 .Xr yppush 8
 273 process on the master server.
 274 .It Ar mapname
 275 The name of the map to transfer.
 276 .El
 277 .Sh FILES
 278 .Bl -tag -width Pa -compact
 279 .It Pa /var/yp/[domainname]/[maps]
 280 The
 281 .Tn NIS
 282 maps for a particular
 283 .Tn NIS
 284 domain.
 285 .El
 286 .Sh SEE ALSO
 287 .Xr yp 4 ,
 288 .Xr yppush 8 ,
 289 .Xr ypserv 8
 290 .Sh AUTHORS
 291 .An Bill Paul Aq wpaul@ctr.columbia.edu