1.\" $OpenBSD: rcmd.3,v 1.27 2007/05/31 19:19:30 jmc 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.Dd $Mdocdate: May 31 2007 $ 31.Dt RCMD 3 32.Os 33.Sh NAME 34.Nm rcmd , 35.Nm rcmd_af , 36.Nm rresvport , 37.Nm rresvport_af , 38.Nm iruserok , 39.Nm ruserok , 40.Nm iruserok_sa 41.Nd routines for returning a stream to a remote command 42.Sh SYNOPSIS 43.Fd #include <unistd.h> 44.Ft int 45.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 46.Ft int 47.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 48.Ft int 49.Fn rresvport "int *port" 50.Ft int 51.Fn rresvport_af "int *port" "int af" 52.Ft int 53.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser" 54.Ft int 55.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 56.Ft int 57.Fn iruserok_sa "const void *sa" "int salen" "int superuser" "const char *ruser" "const char *luser" 58.Sh DESCRIPTION 59The 60.Fn rcmd 61function is used by the superuser to execute a command on a remote 62machine using an authentication scheme based on reserved 63port numbers. 64If the calling process is not setuid, the 65.Ev RSH 66environment variable is set, and 67.Fa inport 68is 69.Dq shell/tcp , 70.Xr rcmdsh 3 71is called instead with the value of 72.Ev RSH . 73Alternately, if the user is not the superuser, 74.Fn rcmd 75will invoke 76.Xr rcmdsh 3 77to run the command via 78.Xr rsh 1 . 79While 80.Fn rcmd 81can handle IPv4 cases only, 82the 83.Fn rcmd_af 84function can handle other cases as well. 85.Pp 86The 87.Fn rresvport 88and 89.Fn rresvport_af 90functions return a descriptor to a socket 91with an address in the privileged port space. 92The 93.Fn iruserok 94and 95.Fn ruserok 96functions are used by servers 97to authenticate clients requesting service with 98.Fn rcmd . 99All four functions are present in the same file and are used 100by the 101.Xr rshd 8 102server (among others). 103.Fn iruserok_sa 104is an address family independent variant of 105.Fn iruserok . 106.Pp 107The 108.Fn rcmd 109function looks up the host 110.Fa *ahost 111using 112.Xr gethostbyname 3 , 113returning \-1 if the host does not exist. 114Otherwise 115.Fa *ahost 116is set to the standard name of the host 117and a connection is established to a server 118residing at the well-known Internet port 119.Fa inport . 120If the user is not the superuser, the only valid port is 121.Dq shell/tcp 122(usually port 514). 123.Pp 124If the connection succeeds, 125a socket in the Internet domain of type 126.Dv SOCK_STREAM 127is returned to the caller, and given to the remote 128command as stdin and stdout. 129If 130.Fa fd2p 131is non-zero, then an auxiliary channel to a control 132process will be set up, and a descriptor for it will be placed 133in 134.Fa *fd2p . 135The control process will return diagnostic 136output from the command (unit 2) on this channel, and will also 137accept bytes on this channel as being 138.Tn UNIX 139signal numbers, to be 140forwarded to the process group of the command. 141If 142.Fa fd2p 143is 144.Va NULL , 145then the standard error (unit 2 of the remote command) will be made 146the same as the standard output and no provision is made for sending 147arbitrary signals to the remote process, although you may be able to 148get its attention by using out-of-band data. 149Note that if the user is not the superuser, 150.Fa fd2p 151must be 152.Va NULL . 153.Pp 154.Fn rcmd_af 155takes address family in the last argument. 156If the last argument is 157.Dv PF_UNSPEC , 158interpretation of 159.Fa *ahost 160will obey the underlying address resolution like DNS. 161.Pp 162The protocol is described in detail in 163.Xr rshd 8 . 164.Pp 165The 166.Fn rresvport 167and 168.Fn rresvport_af 169functions are used to obtain a socket with a privileged 170address bound to it. 171This socket is suitable for use by 172.Fn rcmd 173and several other functions. 174Privileged Internet ports are those in the range 0 to 175.Va IPPORT_RESERVED - 1 , 176which happens to be 1023. 177Only the superuser is allowed to bind an address of this sort to a socket. 178.Fn rresvport 179and 180.Fn rresvport_af 181need to be seeded with a port number; if that port 182is not available these functions will find another. 183.Pp 184The 185.Fn iruserok 186and 187.Fn ruserok 188functions take a remote host's IP address or name, respectively, 189two user names and a flag indicating whether the local user's 190name is that of the superuser. 191Then, if the user is 192.Em not 193the superuser, it checks the 194.Pa /etc/hosts.equiv 195file. 196If that lookup is not done, or is unsuccessful, the 197.Pa .rhosts 198in the local user's home directory is checked to see if the request for 199service is allowed. 200.Pp 201If this file does not exist, is not a regular file, is owned by anyone 202other than the user or the superuser, or is writeable by anyone other 203than the owner, the check automatically fails. 204Zero is returned if the machine name is listed in the 205.Pa hosts.equiv 206file, or the host and remote user name are found in the 207.Pa .rhosts 208file; otherwise 209.Fn iruserok 210and 211.Fn ruserok 212return \-1. 213If the local domain (as obtained from 214.Xr gethostname 3 ) 215is the same as the remote domain, only the machine name need be specified. 216.Pp 217If the IP address of the remote host is known, 218.Fn iruserok 219should be used in preference to 220.Fn ruserok , 221as it does not require trusting the DNS server for the remote host's domain. 222.Pp 223While 224.Fn iruserok 225can handle IPv4 addresses only, 226.Fn iruserok_sa 227and 228.Fn ruserok 229can handle other address families as well, like IPv6. 230The first argument of 231.Fn iruserok_sa 232is typed as 233.Li "void *" 234to avoid dependency between 235.Aq Pa unistd.h 236and 237.Aq Pa sys/socket.h . 238.Sh DIAGNOSTICS 239The 240.Fn rcmd 241function returns a valid socket descriptor on success. 242It returns \-1 on error and prints a diagnostic message on the standard error. 243.Pp 244The 245.Fn rresvport 246and 247.Fn rresvport_af 248functions return a valid, bound socket descriptor on success. 249It returns \-1 on error with the global value 250.Va errno 251set according to the reason for failure. 252The error code 253.Er EAGAIN 254is overloaded to mean 255.Dq all network ports in use . 256.Sh SEE ALSO 257.Xr rsh 1 , 258.Xr intro 2 , 259.Xr bindresvport 3 , 260.Xr bindresvport_sa 3 , 261.Xr rcmdsh 3 , 262.Xr rshd 8 263.Sh HISTORY 264These 265functions appeared in 266.Bx 4.2 . 267