add .Mt to man pages in libexec/
[dragonfly.git] / 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