]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ |
2 | .\" | |
3 | .\" Copyright (c) 1983, 1991, 1993 | |
4 | .\" The Regents of the University of California. All rights reserved. | |
5 | .\" | |
a9cd9cb7 | 6 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
7 | .\" Redistribution and use in source and binary forms, with or without |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
22 | .\" | |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
8c9302dc | 34 | .\" %%%LICENSE_END |
fea681da MK |
35 | .\" |
36 | .\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 | |
37 | .\" | |
38 | .\" Contributed as Linux man page by David A. Holland, 970908 | |
39 | .\" I have not checked whether the Linux situation is exactly the same. | |
3233d665 | 40 | .\" |
352bedee | 41 | .\" 2007-12-08, mtk, Converted from mdoc to man macros |
3233d665 | 42 | .\" |
4b8c67d9 | 43 | .TH RCMD 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
3233d665 | 44 | .SH NAME |
023a57dc MK |
45 | rcmd, rresvport, iruserok, ruserok, rcmd_af, |
46 | rresvport_af, iruserok_af, ruserok_af \- routines for returning a | |
3233d665 MK |
47 | stream to a remote command |
48 | .SH SYNOPSIS | |
49 | .nf | |
50 | .B #include <netdb.h> \ \ \fP/* Or <unistd.h> on some systems */ | |
68e4db0a | 51 | .PP |
ed3ab3bd | 52 | .BI "int rcmd(char **" ahost ", unsigned short " inport ", const char *" locuser ", " |
7afcdaa1 | 53 | .BI " const char *" remuser ", const char *" cmd ", int *" fd2p ); |
68e4db0a | 54 | .PP |
3233d665 | 55 | .BI "int rresvport(int *" port ); |
68e4db0a | 56 | .PP |
aeb4b1fc | 57 | .BI "int iruserok(uint32_t " raddr ", int " superuser ", " |
3233d665 | 58 | .BI " const char *" ruser ", const char *" luser ); |
68e4db0a | 59 | .PP |
3233d665 MK |
60 | .BI "int ruserok(const char *" rhost ", int " superuser ", " |
61 | .BI " const char *" ruser ", const char *" luser ); | |
68e4db0a | 62 | .PP |
ed3ab3bd | 63 | .BI "int rcmd_af(char **" ahost ", unsigned short " inport ", const char *" locuser ", " |
3960d7a2 | 64 | .BI " const char *" remuser ", const char *" cmd ", int *" fd2p , |
023a57dc | 65 | .BI " sa_family_t " af ); |
68e4db0a | 66 | .PP |
023a57dc | 67 | .BI "int rresvport_af(int *" port ", sa_family_t " af ); |
68e4db0a | 68 | .PP |
ed3ab3bd | 69 | .BI "int iruserok_af(const void *" raddr ", int " superuser ", " |
023a57dc MK |
70 | .BI " const char *" ruser ", const char *" luser \ |
71 | ", sa_family_t " af ); | |
68e4db0a | 72 | .PP |
023a57dc MK |
73 | .BI "int ruserok_af(const char *" rhost ", int " superuser ", " |
74 | .BI " const char *" ruser ", const char *" luser \ | |
75 | ", sa_family_t " af ); | |
3233d665 | 76 | .fi |
68e4db0a | 77 | .PP |
98fed84a MK |
78 | .in -4n |
79 | Feature Test Macro Requirements for glibc (see | |
80 | .BR feature_test_macros (7)): | |
81 | .in | |
68e4db0a | 82 | .PP |
98fed84a | 83 | .BR rcmd (), |
023a57dc | 84 | .BR rcmd_af (), |
98fed84a | 85 | .BR rresvport (), |
023a57dc MK |
86 | .BR rresvport_af (), |
87 | .BR iruserok (), | |
88 | .BR iruserok_af (), | |
89 | .BR ruserok (), | |
90 | .BR ruserok_af (): | |
51c612fb MK |
91 | Since glibc 2.19: |
92 | _DEFAULT_SOURCE | |
93 | Glibc 2.19 and earlier: | |
94 | _BSD_SOURCE | |
3233d665 | 95 | .SH DESCRIPTION |
fea681da | 96 | The |
3233d665 | 97 | .BR rcmd () |
6eb334b2 | 98 | function is used by the superuser to execute a command on |
fea681da | 99 | a remote machine using an authentication scheme based |
6eb334b2 | 100 | on privileged port numbers. |
fea681da | 101 | The |
3233d665 | 102 | .BR rresvport () |
fea681da | 103 | function |
d9cb0d7d | 104 | returns a file descriptor to a socket |
fea681da MK |
105 | with an address in the privileged port space. |
106 | The | |
3233d665 | 107 | .BR iruserok () |
fea681da | 108 | and |
3233d665 | 109 | .BR ruserok () |
fea681da MK |
110 | functions are used by servers |
111 | to authenticate clients requesting service with | |
3233d665 | 112 | .BR rcmd (). |
023a57dc | 113 | All four functions are used by the |
3233d665 | 114 | .BR rshd (8) |
fea681da | 115 | server (among others). |
023a57dc | 116 | .SS rcmd() |
5ec60461 | 117 | .PP |
fea681da | 118 | The |
3233d665 | 119 | .BR rcmd () |
fea681da MK |
120 | function |
121 | looks up the host | |
3233d665 | 122 | .I *ahost |
fea681da | 123 | using |
3233d665 | 124 | .BR gethostbyname (3), |
fea681da | 125 | returning \-1 if the host does not exist. |
2b9b829d | 126 | Otherwise, |
3233d665 | 127 | .I *ahost |
fea681da MK |
128 | is set to the standard name of the host |
129 | and a connection is established to a server | |
130 | residing at the well-known Internet port | |
3233d665 | 131 | .IR inport . |
5ec60461 | 132 | .PP |
fea681da MK |
133 | If the connection succeeds, |
134 | a socket in the Internet domain of type | |
3233d665 | 135 | .BR SOCK_STREAM |
fea681da | 136 | is returned to the caller, and given to the remote |
c13182ef | 137 | command as |
3233d665 | 138 | .IR stdin |
fea681da | 139 | and |
3233d665 | 140 | .IR stdout . |
fea681da | 141 | If |
3233d665 | 142 | .I fd2p |
c7094399 | 143 | is nonzero, then an auxiliary channel to a control |
d9cb0d7d | 144 | process will be set up, and a file descriptor for it will be placed |
fea681da | 145 | in |
3233d665 | 146 | .IR *fd2p . |
fea681da MK |
147 | The control process will return diagnostic |
148 | output from the command (unit 2) on this channel, and will also | |
008f1ecc | 149 | accept bytes on this channel as being UNIX signal numbers, to be |
fea681da MK |
150 | forwarded to the process group of the command. |
151 | If | |
3233d665 | 152 | .I fd2p |
c13182ef | 153 | is 0, then the |
3233d665 | 154 | .IR stderr |
fea681da | 155 | (unit 2 of the remote |
c13182ef | 156 | command) will be made the same as the |
3233d665 | 157 | .IR stdout |
fea681da MK |
158 | and no |
159 | provision is made for sending arbitrary signals to the remote process, | |
160 | although you may be able to get its attention by using out-of-band data. | |
5ec60461 | 161 | .PP |
fea681da | 162 | The protocol is described in detail in |
3233d665 | 163 | .BR rshd (8). |
023a57dc | 164 | .SS rresvport() |
5ec60461 | 165 | .PP |
fea681da | 166 | The |
3233d665 | 167 | .BR rresvport () |
fea681da | 168 | function is used to obtain a socket with a privileged |
aa104c88 | 169 | port bound to it. |
c13182ef | 170 | This socket is suitable for use by |
3233d665 | 171 | .BR rcmd () |
c13182ef | 172 | and several other functions. |
aa104c88 MK |
173 | Privileged ports are those in the range 0 to 1023. |
174 | Only a privileged process | |
ed1ba8a5 MK |
175 | (on Linux: a process that has the |
176 | .B CAP_NET_BIND_SERVICE | |
177 | capability in the user namespace governing its network namespace). | |
aa104c88 MK |
178 | is allowed to bind to a privileged port. |
179 | In the glibc implementation, | |
180 | this function restricts its search to the ports from 512 to 1023. | |
181 | The | |
182 | .I port | |
183 | argument is value-result: | |
184 | the value it supplies to the call is used as the starting point | |
185 | for a circular search of the port range; | |
186 | on (successful) return, it contains the port number that was bound to. | |
023a57dc MK |
187 | .\" |
188 | .SS iruserok() and ruserok() | |
5ec60461 | 189 | .PP |
fea681da | 190 | The |
3233d665 | 191 | .BR iruserok () |
fea681da | 192 | and |
3233d665 | 193 | .BR ruserok () |
fea681da | 194 | functions take a remote host's IP address or name, respectively, |
18701562 | 195 | two usernames and a flag indicating whether the local user's |
2c8d1c7d | 196 | name is that of the superuser. |
fea681da | 197 | Then, if the user is |
3233d665 | 198 | .I not |
2c8d1c7d | 199 | the superuser, it checks the |
3233d665 | 200 | .IR /etc/hosts.equiv |
fea681da MK |
201 | file. |
202 | If that lookup is not done, or is unsuccessful, the | |
3233d665 | 203 | .IR .rhosts |
fea681da MK |
204 | in the local user's home directory is checked to see if the request for |
205 | service is allowed. | |
5ec60461 | 206 | .PP |
fea681da | 207 | If this file does not exist, is not a regular file, is owned by anyone |
c32f10a1 NF |
208 | other than the user or the superuser, is writable by anyone other |
209 | than the owner, or is hardlinked anywhere, the check automatically fails. | |
fea681da | 210 | Zero is returned if the machine name is listed in the |
3233d665 | 211 | .IR hosts.equiv |
18701562 | 212 | file, or the host and remote username are found in the |
3233d665 | 213 | .IR .rhosts |
fea681da | 214 | file; otherwise |
3233d665 | 215 | .BR iruserok () |
fea681da | 216 | and |
3233d665 | 217 | .BR ruserok () |
fea681da MK |
218 | return \-1. |
219 | If the local domain (as obtained from | |
a3c5b73c | 220 | .BR gethostname (2)) |
fea681da | 221 | is the same as the remote domain, only the machine name need be specified. |
5ec60461 | 222 | .PP |
fea681da | 223 | If the IP address of the remote host is known, |
3233d665 | 224 | .BR iruserok () |
fea681da | 225 | should be used in preference to |
3233d665 | 226 | .BR ruserok (), |
fea681da | 227 | as it does not require trusting the DNS server for the remote host's domain. |
023a57dc MK |
228 | .SS *_af() variants |
229 | All of the functions described above work with IPv4 | |
230 | .RB ( AF_INET ) | |
231 | sockets. | |
232 | The "_af" variants take an extra argument that allows the | |
233 | socket address family to be specified. | |
234 | For these functions, the | |
235 | .I af | |
236 | argument can be specified as | |
237 | .BR AF_INET | |
238 | or | |
239 | .BR AF_INET6 . | |
240 | In addition, | |
241 | .BR rcmd_af () | |
242 | supports the use of | |
243 | .BR AF_UNSPEC . | |
3233d665 | 244 | .SH RETURN VALUE |
fea681da | 245 | The |
3233d665 | 246 | .BR rcmd () |
fea681da MK |
247 | function |
248 | returns a valid socket descriptor on success. | |
249 | It returns \-1 on error and prints a diagnostic message on the standard error. | |
5ec60461 | 250 | .PP |
fea681da | 251 | The |
3233d665 | 252 | .BR rresvport () |
fea681da MK |
253 | function |
254 | returns a valid, bound socket descriptor on success. | |
255 | It returns \-1 on error with the global value | |
3233d665 | 256 | .I errno |
fea681da MK |
257 | set according to the reason for failure. |
258 | The error code | |
3233d665 MK |
259 | .BR EAGAIN |
260 | is overloaded to mean "All network ports in use." | |
847e0d88 | 261 | .PP |
023a57dc MK |
262 | For information on the return from |
263 | .BR ruserok () | |
264 | and | |
265 | .BR iruserok (), | |
266 | see above. | |
267 | .SH VERSIONS | |
268 | The functions | |
269 | .BR iruserok_af (), | |
270 | .BR rcmd_af (), | |
271 | .BR rresvport_af (), | |
272 | and | |
273 | .BR ruserok_af () | |
274 | functions are provide in glibc since version 2.2. | |
e196c900 ZL |
275 | .SH ATTRIBUTES |
276 | For an explanation of the terms used in this section, see | |
277 | .BR attributes (7). | |
278 | .TS | |
279 | allbox; | |
78b0e70a | 280 | lbw27 lb lb |
e196c900 ZL |
281 | l l l. |
282 | Interface Attribute Value | |
283 | T{ | |
284 | .BR rcmd (), | |
285 | .BR rcmd_af () | |
286 | T} Thread safety MT-Unsafe | |
287 | T{ | |
288 | .BR rresvport (), | |
289 | .BR rresvport_af () | |
290 | T} Thread safety MT-Safe | |
291 | T{ | |
292 | .BR iruserok (), | |
293 | .BR ruserok (), | |
78b0e70a | 294 | .br |
e196c900 ZL |
295 | .BR iruserok_af (), |
296 | .BR ruserok_af () | |
297 | T} Thread safety MT-Safe locale | |
298 | .TE | |
847e0d88 | 299 | .sp 1 |
47297adb | 300 | .SH CONFORMING TO |
8f52ec9e | 301 | Not in POSIX.1. |
a7fadb55 MK |
302 | Present on the BSDs, Solaris, and many other systems. |
303 | These | |
c13182ef | 304 | functions appeared in |
3233d665 | 305 | 4.2BSD. |
023a57dc MK |
306 | The "_af" variants are more recent additions, |
307 | and are not present on as wide a range of systems. | |
98fed84a MK |
308 | .SH BUGS |
309 | .BR iruserok () | |
023a57dc MK |
310 | and |
311 | .BR iruserok_af () | |
312 | are declared in glibc headers only since version 2.12. | |
98fed84a MK |
313 | .\" Bug filed 25 Nov 2007: |
314 | .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=5399 | |
3233d665 MK |
315 | .SH SEE ALSO |
316 | .BR rlogin (1), | |
317 | .BR rsh (1), | |
318 | .BR intro (2), | |
319 | .BR rexec (3), | |
320 | .BR rexecd (8), | |
321 | .BR rlogind (8), | |
322 | .BR rshd (8) |