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