1.\" $OpenBSD: rcmd.3,v 1.23 2000/12/24 00:30:56 aaron 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd June 4, 1993 35.Dt RCMD 3 36.Os 37.Sh NAME 38.Nm rcmd , 39.Nm rcmd_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 SYNOPSIS 47.Fd #include <unistd.h> 48.Ft int 49.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 50.Ft int 51.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 52.Ft int 53.Fn rresvport "int *port" 54.Ft int 55.Fn rresvport_af "int *port" "int af" 56.Ft int 57.Fn iruserok "u_int32_t 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 iruserok_sa "const void *sa" "int salen" "int superuser" "const char *ruser" 62.Sh DESCRIPTION 63The 64.Fn rcmd 65function is used by the superuser to execute a command on a remote 66machine using an authentication scheme based on reserved 67port numbers. 68If the calling process is not setuid, the 69.Ev RSH 70environment variable is set, and 71.Fa inport 72is 73.Dq shell/tcp , 74.Xr rcmdsh 3 75is called instead with the value of 76.Ev RSH . 77Alternately, if the user is not the superuser, 78.Fn rcmd 79will invoke 80.Xr rcmdsh 3 81to run the command via 82.Xr rsh 1 . 83While 84.Fn rcmd 85can handle IPv4 cases only, 86the 87.Fn rcmd_af 88function can handle other cases as well. 89.Pp 90The 91.Fn rresvport 92and 93.Fn rresvport_af 94functions return a descriptor to a socket 95with an address in the privileged port space. 96The 97.Fn iruserok 98and 99.Fn ruserok 100functions are used by servers 101to authenticate clients requesting service with 102.Fn rcmd . 103All four functions are present in the same file and are used 104by the 105.Xr rshd 8 106server (among others). 107.Fn iruserok_sa 108is an address family independent variant of 109.Fn iruserok . 110.Pp 111The 112.Fn rcmd 113function looks up the host 114.Fa *ahost 115using 116.Xr gethostbyname 3 , 117returning \-1 if the host does not exist. 118Otherwise 119.Fa *ahost 120is set to the standard name of the host 121and a connection is established to a server 122residing at the well-known Internet port 123.Fa inport . 124If the user is not the superuser, the only valid port is 125.Dq shell/tcp 126(usually port 514). 127.Pp 128If the connection succeeds, 129a socket in the Internet domain of type 130.Dv SOCK_STREAM 131is returned to the caller, and given to the remote 132command as stdin and stdout. 133If 134.Fa fd2p 135is non-zero, then an auxiliary channel to a control 136process will be set up, and a descriptor for it will be placed 137in 138.Fa *fd2p . 139The control process will return diagnostic 140output from the command (unit 2) on this channel, and will also 141accept bytes on this channel as being 142.Tn UNIX 143signal numbers, to be 144forwarded to the process group of the command. 145If 146.Fa fd2p 147is 148.Va NULL , 149then the standard error (unit 2 of the remote command) will be made 150the same as the standard output and no provision is made for sending 151arbitrary signals to the remote process, although you may be able to 152get its attention by using out-of-band data. 153Note that if the user is not the superuser, 154.Fa fd2p 155must be 156.Va NULL . 157.Pp 158.Fn rcmd_af 159takes address family in the last argument. 160If the last argument is 161.Dv PF_UNSPEC , 162interpretation of 163.Fa *ahost 164will obey the underlying address resolution like DNS. 165.Pp 166The protocol is described in detail in 167.Xr rshd 8 . 168.Pp 169The 170.Fn rresvport 171and 172.Fn rresvport_af 173functions are used to obtain a socket with a privileged 174address bound to it. 175This socket is suitable for use by 176.Fn rcmd 177and several other functions. 178Privileged Internet ports are those in the range 0 to 179.Va IPPORT_RESERVED - 1 , 180which happens to be 1023. 181Only the superuser is allowed to bind an address of this sort to a socket. 182.Fn rresvport 183and 184.Fn rresvport_af 185need to be seeded with a port number; if that port 186is not available these functions will find another. 187.Pp 188The 189.Fn iruserok 190and 191.Fn ruserok 192functions take a remote host's IP address or name, respectively, 193two user names and a flag indicating whether the local user's 194name is that of the superuser. 195Then, if the user is 196.Em not 197the superuser, it checks the 198.Pa /etc/hosts.equiv 199file. 200If that lookup is not done, or is unsuccessful, the 201.Pa .rhosts 202in the local user's home directory is checked to see if the request for 203service is allowed. 204.Pp 205If this file does not exist, is not a regular file, is owned by anyone 206other than the user or the superuser, or is writeable by anyone other 207than the owner, the check automatically fails. 208Zero is returned if the machine name is listed in the 209.Pa hosts.equiv 210file, or the host and remote user name are found in the 211.Pa .rhosts 212file; otherwise 213.Fn iruserok 214and 215.Fn ruserok 216return \-1. 217If the local domain (as obtained from 218.Xr gethostname 3 ) 219is the same as the remote domain, only the machine name need be specified. 220.Pp 221If the IP address of the remote host is known, 222.Fn iruserok 223should be used in preference to 224.Fn ruserok , 225as it does not require trusting the DNS server for the remote host's domain. 226.Pp 227While 228.Fn iruserok 229can handle IPv4 addresses only, 230.Fn iruserok_sa 231and 232.Fn ruserok 233can handle other address families as well, like IPv6. 234The first argument of 235.Fn iruserok_sa 236is typed as 237.Li "void *" 238to avoid dependency between 239.Aq Pa unistd.h 240and 241.Aq Pa sys/socket.h . 242.Sh DIAGNOSTICS 243The 244.Fn rcmd 245function returns a valid socket descriptor on success. 246It returns \-1 on error and prints a diagnostic message on the standard error. 247.Pp 248The 249.Fn rresvport 250and 251.Fn rresvport_af 252functions return a valid, bound socket descriptor on success. 253It returns \-1 on error with the global value 254.Va errno 255set according to the reason for failure. 256The error code 257.Er EAGAIN 258is overloaded to mean 259.Dq all network ports in use . 260.Sh SEE ALSO 261.Xr rlogin 1 , 262.Xr rsh 1 , 263.Xr intro 2 , 264.Xr bindresvport 3 , 265.Xr bindresvport_sa 3 , 266.Xr rcmdsh 3 , 267.Xr rexec 3 , 268.Xr rexecd 8 , 269.Xr rlogind 8 , 270.Xr rshd 8 271.Sh HISTORY 272These 273functions appeared in 274.Bx 4.2 . 275