xref: /freebsd/lib/libc/net/rcmd.3 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
1.\" Copyright (c) 1983, 1991, 1993
2.\"	The Regents of the University of California.  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 the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     From: @(#)rcmd.3	8.1 (Berkeley) 6/4/93
33.\" $FreeBSD$
34.\"
35.Dd March 3, 2000
36.Dt RCMD 3
37.Os
38.Sh NAME
39.Nm rcmd ,
40.Nm rresvport ,
41.Nm iruserok ,
42.Nm ruserok ,
43.Nm rcmd_af ,
44.Nm rresvport_af ,
45.Nm iruserok_sa
46.Nd routines for returning a stream to a remote command
47.Sh LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In unistd.h
51.Ft int
52.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
53.Ft int
54.Fn rresvport "int *port"
55.Ft int
56.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser"
57.Ft int
58.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser"
59.Ft int
60.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
61.Ft int
62.Fn rresvport_af "int *port" "int af"
63.Ft int
64.Fn iruserok_sa "const void *addr" "int addrlen" "int superuser" "const char *ruser" "const char *luser"
65.Sh DESCRIPTION
66The
67.Fn rcmd
68function
69is used by the super-user to execute a command on
70a remote machine using an authentication scheme based
71on reserved port numbers.
72The
73.Fn rresvport
74function
75returns a descriptor to a socket
76with an address in the privileged port space.
77The
78.Fn ruserok
79function
80is used by servers
81to authenticate clients requesting service with
82.Fn rcmd .
83All three functions are present in the same file and are used
84by the
85.Xr rshd 8
86server (among others).
87.Pp
88The
89.Fn rcmd
90function
91looks up the host
92.Fa *ahost
93using
94.Xr gethostbyname 3 ,
95returning -1 if the host does not exist.
96Otherwise
97.Fa *ahost
98is set to the standard name of the host
99and a connection is established to a server
100residing at the well-known Internet port
101.Fa inport .
102.Pp
103If the connection succeeds,
104a socket in the Internet domain of type
105.Dv SOCK_STREAM
106is returned to the caller, and given to the remote
107command as
108.Dv stdin
109and
110.Dv stdout .
111If
112.Fa fd2p
113is non-zero, then an auxiliary channel to a control
114process will be set up, and a descriptor for it will be placed
115in
116.Fa *fd2p .
117The control process will return diagnostic
118output from the command (unit 2) on this channel, and will also
119accept bytes on this channel as being
120.Ux
121signal numbers, to be
122forwarded to the process group of the command.
123If
124.Fa fd2p
125is 0, then the
126.Dv stderr
127(unit 2 of the remote
128command) will be made the same as the
129.Dv stdout
130and no
131provision is made for sending arbitrary signals to the remote process,
132although you may be able to get its attention by using out-of-band data.
133.Pp
134The protocol is described in detail in
135.Xr rshd 8 .
136.Pp
137The
138.Fn rresvport
139function is used to obtain a socket to which an address with a Privileged
140Internet port is bound.
141This socket is suitable for use by
142.Fn rcmd
143and several other functions.
144Privileged Internet ports are those in the range 0 to 1023.
145Only the super-user is allowed to bind an address of this sort
146to a socket.
147.Pp
148The
149.Fn iruserok
150and
151.Fn ruserok
152functions take a remote host's IP address or name, as returned by the
153.Xr gethostbyname 3
154routines, two user names and a flag indicating whether the local user's
155name is that of the super-user.
156Then, if the user is
157.Em NOT
158the super-user, it checks the
159.Pa /etc/hosts.equiv
160file.
161If that lookup is not done, or is unsuccessful, the
162.Pa .rhosts
163in the local user's home directory is checked to see if the request for
164service is allowed.
165.Pp
166If this file does not exist, is not a regular file, is owned by anyone
167other than the user or the super-user, or is writable by anyone other
168than the owner, the check automatically fails.
169Zero is returned if the machine name is listed in the
170.Dq Pa hosts.equiv
171file, or the host and remote user name are found in the
172.Dq Pa .rhosts
173file; otherwise
174.Fn iruserok
175and
176.Fn ruserok
177return -1.
178If the local domain (as obtained from
179.Xr gethostname 3 )
180is the same as the remote domain, only the machine name need be specified.
181.Pp
182The
183.Fn iruserok
184function is strongly preferred for security reasons.
185It requires trusting the local DNS at most, while the
186.Fn ruserok
187function requires trusting the entire DNS, which can be spoofed.
188.Pp
189The functions with an
190.Dq Li _af
191or
192.Dq Li _sa
193suffix, i.e.,
194.Fn rcmd_af ,
195.Fn rresvport_af
196and
197.Fn iruserok_sa ,
198work the same as the corresponding functions without a
199suffix, except that they are capable of handling both IPv6 and IPv4 ports.
200.Pp
201The
202.Dq Li _af
203suffix means that the function has an additional
204.Fa af
205argument which is used to specify the address family,
206(see below).
207The
208.Fa af
209argument extension is implemented for functions
210that have no binary address argument.
211Instead, the
212.Fa af
213argument specifies which address family is desired.
214.Pp
215The
216.Dq Li _sa
217suffix means that the function has general socket address and
218length arguments.
219As the socket address is a protocol independent data structure,
220IPv4 and IPv6 socket address can be passed as desired.
221The
222.Fa sa
223argument extension is implemented for functions
224that pass a protocol dependent binary address argument.
225The argument needs to be replaced with a more general address structure
226to support multiple address families in a general way.
227.Pp
228The functions with neither an
229.Dq Li _af
230suffix nor an
231.Dq Li _sa
232suffix work for IPv4 only, except for
233.Fn ruserok
234which can handle both IPv6 and IPv4.
235To switch the address family, the
236.Fa af
237argument must be filled with
238.Dv AF_INET ,
239or
240.Dv AF_INET6 .
241For
242.Fn rcmd_af ,
243.Dv PF_UNSPEC
244is also allowed.
245.Sh DIAGNOSTICS
246The
247.Fn rcmd
248function
249returns a valid socket descriptor on success.
250It returns -1 on error and prints a diagnostic message
251on the standard error.
252.Pp
253The
254.Fn rresvport
255function
256returns a valid, bound socket descriptor on success.
257It returns -1 on error with the global value
258.Va errno
259set according to the reason for failure.
260The error code
261.Er EAGAIN
262is overloaded to mean ``All network ports in use.''
263.Sh SEE ALSO
264.Xr rlogin 1 ,
265.Xr rsh 1 ,
266.Xr intro 2 ,
267.Xr rexec 3 ,
268.Xr rexecd 8 ,
269.Xr rlogind 8 ,
270.Xr rshd 8
271.Pp
272.Rs
273.%A W. Stevens
274.%A M. Thomas
275.%T "Advanced Socket API for IPv6"
276.%O RFC2292
277.Re
278.Rs
279.%A W. Stevens
280.%A M. Thomas
281.%A E. Nordmark
282.%T "Advanced Socket API for IPv6"
283.%O draft-ietf-ipngwg-rfc2292bis-01.txt
284.Re
285.Sh HISTORY
286Most of these
287functions appeared in
288.Bx 4.2 .
289The
290.Fn rresvport_af
291function
292appeared in RFC2292, and was implemented by the WIDE project
293for the Hydrangea IPv6 protocol stack kit.
294The
295.Fn rcmd_af
296function
297appeared in draft-ietf-ipngwg-rfc2292bis-01.txt,
298and was implemented in the WIDE/KAME IPv6 protocol stack kit.
299The
300.Fn iruserok_sa
301function
302appeared in discussion on the IETF ipngwg mailing list,
303and was implemented in
304.Fx 4.0 .
305