Also make clean for internal pic archives.
[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 .\" $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