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