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