| blob | 84ef5c74c253bbe905ae770f119e77649f8af805 |
1 .\" $NetBSD: rcmd.3,v 1.26 2005/03/31 15:45:53 christos Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd March 30, 2005
33 .Dt RCMD 3
34 .Os
35 .Sh NAME
36 .Nm rcmd ,
37 .Nm orcmd ,
38 .Nm rcmd_af ,
39 .Nm orcmd_af ,
40 .Nm rresvport ,
41 .Nm rresvport_af ,
42 .Nm iruserok ,
43 .Nm ruserok ,
44 .Nm iruserok_sa
45 .Nd routines for returning a stream to a remote command
46 .Sh LIBRARY
47 .Lb libc
48 .Sh SYNOPSIS
49 .In unistd.h
50 .Ft int
51 .Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
52 .Ft int
53 .Fn orcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
54 .Ft int
55 .Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
56 .Ft int
57 .Fn orcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
58 .Ft int
59 .Fn rresvport "int *port"
60 .Ft int
61 .Fn rresvport_af "int *port" "int family"
62 .Ft int
63 .Fn iruserok "uint32_t raddr" "int superuser" "const char *ruser" "const char *luser"
64 .Ft int
65 .Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser"
66 .Ft int
67 .Fn iruserok_sa "const void *raddr" "int rlen" "int superuser" "const char *ruser" "const char *luser"
68 .Sh DESCRIPTION
69 The
70 .Fn rcmd
71 function is available for use by anyone to run commands on a
72 remote system. It acts like the
73 .Fn orcmd
74 command, with the exception that it makes a call out to the
75 .Xr rcmd 1
76 command, or any other user-specified command, to perform the
77 actual connection (thus not requiring
78 that the caller be running as the super-user), and is only
79 available for the
80 .Dq shell/tcp
81 port.
82 The
83 .Fn orcmd
84 function
85 is used by the super-user to execute a command on
86 a remote machine using an authentication scheme based
87 on reserved port numbers.
88 While
89 .Fn rcmd
90 and
91 .Fn orcmd
92 can only handle IPv4 address in the first argument,
93 .Fn rcmd_af
94 and
95 .Fn orcmd_af
96 can handle other cases as well.
97 The
98 .Fn rresvport
99 function
100 returns a descriptor to a socket
101 with an address in the privileged port space.
102 The
103 .Fn rresvport_af
104 function is similar to
105 .Fn rresvport ,
106 but you can explicitly specify the address family to use.
107 Calling
108 .Fn rresvport_af
109 with
110 .Dv AF_INET
111 has the same effect as
112 .Fn rresvport .
113 The
114 .Fn iruserok
115 and
116 .Fn ruserok
117 functions are used by servers
118 to authenticate clients requesting service with
119 .Fn rcmd .
120 All six functions are present in the same file and are used
121 by the
122 .Xr rshd 8
123 server (among others).
124 .Fn iruserok_sa
125 is an address family independent variant of
126 .Fn iruserok .
127 .Pp
128 The
129 .Fn rcmd
130 function
131 looks up the host
132 .Fa *ahost
133 using
134 .Xr gethostbyname 3 ,
135 returning \-1 if the host does not exist.
136 Otherwise
137 .Fa *ahost
138 is set to the standard name of the host
139 and a connection is established to a server
140 residing at the well-known Internet port
141 .Fa inport .
142 .Pp
143 If the connection succeeds,
144 a socket in the Internet domain of type
145 .Dv SOCK_STREAM
146 is returned to the caller, and given to the remote
147 command as
148 .Em stdin
149 and
150 .Em stdout .
151 If
152 .Fa fd2p
153 is non-zero, then an auxiliary channel to a control
154 process will be set up, and a descriptor for it will be placed
155 in
156 .Fa *fd2p .
157 The control process will return diagnostic
158 output from the command (unit 2) on this channel, and will also
159 accept bytes on this channel as being
160 .Ux
161 signal numbers, to be
162 forwarded to the process group of the command.
163 If
164 .Fa fd2p
165 is 0, then the
166 .Em stderr
167 (unit 2 of the remote
168 command) will be made the same as the
169 .Em stdout
170 and no
171 provision is made for sending arbitrary signals to the remote process,
172 although you may be able to get its attention by using out-of-band data.
173 .Pp
174 .Fn rcmd_af
175 and
176 .Fn orcmd_af
177 take address family in the last argument.
178 If the last argument is
179 .Dv PF_UNSPEC ,
180 interpretation of
181 .Fa *ahost
182 will obey the underlying address resolution like DNS.
183 .Pp
184 The protocol is described in detail in
185 .Xr rshd 8 .
186 .Pp
187 The
188 .Fn rresvport
189 and
190 .Fn rresvport_af
191 functions are used to obtain a socket with a privileged
192 address bound to it. This socket is suitable for use
193 by
194 .Fn rcmd
195 and several other functions. Privileged Internet ports are those
196 in the range 0 to 1023. Only the super-user
197 is allowed to bind an address of this sort to a socket.
198 .Pp
199 The
200 .Fn iruserok
201 and
202 .Fn ruserok
203 functions take a remote host's IP address or name, respectively,
204 two user names and a flag indicating whether the local user's
205 name is that of the super-user.
206 Then, if the user is
207 .Em NOT
208 the super-user, it checks the
209 .Pa /etc/hosts.equiv
210 file.
211 If that lookup is not done, or is unsuccessful, the
212 .Pa .rhosts
213 in the local user's home directory is checked to see if the request for
214 service is allowed.
215 .Pp
216 If this file does not exist, is not a regular file, is owned by anyone
217 other than the user or the super-user, or is writable by anyone other
218 than the owner, the check automatically fails.
219 Zero is returned if the machine name is listed in the
220 .Dq Pa hosts.equiv
221 file, or the host and remote user name are found in the
222 .Dq Pa .rhosts
223 file; otherwise
224 .Fn iruserok
225 and
226 .Fn ruserok
227 return \-1.
228 If the local domain (as obtained from
229 .Xr gethostname 3 )
230 is the same as the remote domain, only the machine name need be specified.
231 .Pp
232 If the IP address of the remote host is known,
233 .Fn iruserok
234 should be used in preference to
235 .Fn ruserok ,
236 as it does not require trusting the DNS server for the remote host's domain.
237 .Pp
238 While
239 .Fn iruserok
240 can handle IPv4 addresses only,
241 .Fn iruserok_sa
242 and
243 .Fn ruserok
244 can handle other address families as well, like IPv6.
245 The first argument of
246 .Fn iruserok_sa
247 is typed as
248 .Fa "void *"
249 to avoid dependency between
250 .Aq Li unistd.h
251 and
252 .Aq Li sys/socket.h .
253 .Sh ENVIRONMENT
254 .Bl -tag -width RCMD_CMDxx -compact
255 .It Ev RCMD_CMD
256 When using the
257 .Fn rcmd
258 function, this variable is used as the program to run instead of
259 .Xr rcmd 1 .
260 .El
261 .Sh DIAGNOSTICS
262 The
263 .Fn rcmd
264 function
265 returns a valid socket descriptor on success.
266 It returns \-1 on error and prints a diagnostic message on the standard error.
267 .Pp
268 The
269 .Fn rresvport
270 and
271 .Fn rresvport_af
272 function
273 return a valid, bound socket descriptor on success.
274 They return \-1 on error with the global value
275 .Va errno
276 set according to the reason for failure.
277 The error code
278 .Dv EAGAIN
279 is overloaded to mean ``All network ports in use.''
280 .Sh SEE ALSO
281 .Xr rcmd 1 ,
282 .Xr rlogin 1 ,
283 .Xr rsh 1 ,
284 .Xr intro 2 ,
285 .Xr rexec 3 ,
286 .Xr hosts.equiv 5 ,
287 .Xr rhosts 5 ,
288 .Xr rexecd 8 ,
289 .Xr rlogind 8 ,
290 .Xr rshd 8
291 .Sh HISTORY
292 The
293 .Fn orcmd ,
294 .Fn rresvport ,
295 .Fn iruserok
296 and
297 .Fn ruserok
298 functions appeared in
299 .Bx 4.2 ,
300 where the
301 .Fn orcmd
302 function was called
303 .Fn rcmd .
304 The (newer)
305 .Fn rcmd
306 function appeared in
307 .Nx 1.3 .
308 .Fn rcmd_af
309 and
310 .Fn rresvport_af
311 were defined in RFC2292.