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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)rcmd.3 8.1 (Berkeley) 6/4/93 29.\" 30.Dd March 3, 2000 31.Dt RCMD 3 32.Os 33.Sh NAME 34.Nm rcmd , 35.Nm rresvport , 36.Nm iruserok , 37.Nm ruserok , 38.Nm rcmd_af , 39.Nm rresvport_af , 40.Nm iruserok_sa 41.Nd routines for returning a stream to a remote command 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In unistd.h 46.Ft int 47.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 48.Ft int 49.Fn rresvport "int *port" 50.Ft int 51.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" 52.Ft int 53.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 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 rresvport_af "int *port" "int af" 58.Ft int 59.Fn iruserok_sa "const void *addr" "int addrlen" "int superuser" "const char *ruser" "const char *luser" 60.Sh DESCRIPTION 61The 62.Fn rcmd 63function 64is used by the super-user to execute a command on 65a remote machine using an authentication scheme based 66on reserved port numbers. 67The 68.Fn rresvport 69function 70returns a descriptor to a socket 71with an address in the privileged port space. 72The 73.Fn ruserok 74function 75is used by servers 76to authenticate clients requesting service with 77.Fn rcmd . 78All three functions are present in the same file and are used 79by the 80.Xr rshd 8 81server (among others). 82.Pp 83The 84.Fn rcmd 85function 86looks up the host 87.Fa *ahost 88using 89.Xr gethostbyname 3 , 90returning -1 if the host does not exist. 91Otherwise 92.Fa *ahost 93is set to the standard name of the host 94and a connection is established to a server 95residing at the well-known Internet port 96.Fa inport . 97.Pp 98If the connection succeeds, 99a socket in the Internet domain of type 100.Dv SOCK_STREAM 101is returned to the caller, and given to the remote 102command as 103.Dv stdin 104and 105.Dv stdout . 106If 107.Fa fd2p 108is non-zero, then an auxiliary channel to a control 109process will be set up, and a descriptor for it will be placed 110in 111.Fa *fd2p . 112The control process will return diagnostic 113output from the command (unit 2) on this channel, and will also 114accept bytes on this channel as being 115.Ux 116signal numbers, to be 117forwarded to the process group of the command. 118If 119.Fa fd2p 120is 0, then the 121.Dv stderr 122(unit 2 of the remote 123command) will be made the same as the 124.Dv stdout 125and no 126provision is made for sending arbitrary signals to the remote process, 127although you may be able to get its attention by using out-of-band data. 128.Pp 129The protocol is described in detail in 130.Xr rshd 8 . 131.Pp 132The 133.Fn rresvport 134function is used to obtain a socket to which an address with a Privileged 135Internet port is bound. 136This socket is suitable for use by 137.Fn rcmd 138and several other functions. 139Privileged Internet ports are those in the range 0 to 1023. 140Only the super-user is allowed to bind an address of this sort 141to a socket. 142.Pp 143The 144.Fn iruserok 145and 146.Fn ruserok 147functions take a remote host's IP address or name, as returned by the 148.Xr gethostbyname 3 149routines, two user names and a flag indicating whether the local user's 150name is that of the super-user. 151Then, if the user is 152.Em NOT 153the super-user, it checks the 154.Pa /etc/hosts.equiv 155file. 156If that lookup is not done, or is unsuccessful, the 157.Pa .rhosts 158in the local user's home directory is checked to see if the request for 159service is allowed. 160.Pp 161If this file does not exist, is not a regular file, is owned by anyone 162other than the user or the super-user, or is writable by anyone other 163than the owner, the check automatically fails. 164Zero is returned if the machine name is listed in the 165.Dq Pa hosts.equiv 166file, or the host and remote user name are found in the 167.Dq Pa .rhosts 168file; otherwise 169.Fn iruserok 170and 171.Fn ruserok 172return -1. 173If the local domain (as obtained from 174.Xr gethostname 3 ) 175is the same as the remote domain, only the machine name need be specified. 176.Pp 177The 178.Fn iruserok 179function is strongly preferred for security reasons. 180It requires trusting the local DNS at most, while the 181.Fn ruserok 182function requires trusting the entire DNS, which can be spoofed. 183.Pp 184The functions with an 185.Dq Li _af 186or 187.Dq Li _sa 188suffix, i.e., 189.Fn rcmd_af , 190.Fn rresvport_af 191and 192.Fn iruserok_sa , 193work the same as the corresponding functions without a 194suffix, except that they are capable of handling both IPv6 and IPv4 ports. 195.Pp 196The 197.Dq Li _af 198suffix means that the function has an additional 199.Fa af 200argument which is used to specify the address family, 201(see below). 202The 203.Fa af 204argument extension is implemented for functions 205that have no binary address argument. 206Instead, the 207.Fa af 208argument specifies which address family is desired. 209.Pp 210The 211.Dq Li _sa 212suffix means that the function has general socket address and 213length arguments. 214As the socket address is a protocol independent data structure, 215IPv4 and IPv6 socket address can be passed as desired. 216The 217.Fa sa 218argument extension is implemented for functions 219that pass a protocol dependent binary address argument. 220The argument needs to be replaced with a more general address structure 221to support multiple address families in a general way. 222.Pp 223The functions with neither an 224.Dq Li _af 225suffix nor an 226.Dq Li _sa 227suffix work for IPv4 only, except for 228.Fn ruserok 229which can handle both IPv6 and IPv4. 230To switch the address family, the 231.Fa af 232argument must be filled with 233.Dv AF_INET , 234or 235.Dv AF_INET6 . 236For 237.Fn rcmd_af , 238.Dv PF_UNSPEC 239is also allowed. 240.Sh ENVIRONMENT 241.Bl -tag -width RSH 242.It Ev RSH 243When using the 244.Fn rcmd 245function, this variable is used as the program to run instead of 246.Xr rsh 1 . 247.El 248.Sh DIAGNOSTICS 249The 250.Fn rcmd 251function 252returns a valid socket descriptor on success. 253It returns -1 on error and prints a diagnostic message 254on the standard error. 255.Pp 256The 257.Fn rresvport 258function 259returns a valid, bound socket descriptor on success. 260It returns -1 on error with the global value 261.Va errno 262set according to the reason for failure. 263The error code 264.Er EAGAIN 265is overloaded to mean ``All network ports in use.'' 266.Sh SEE ALSO 267.Xr rlogin 1 , 268.Xr rsh 1 , 269.Xr intro 2 , 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 RFC3542 285.Re 286.Sh HISTORY 287Most of these 288functions appeared in 289.Bx 4.2 . 290The 291.Fn rresvport_af 292function 293appeared in RFC2292, and was implemented by the WIDE project 294for the Hydrangea IPv6 protocol stack kit. 295The 296.Fn rcmd_af 297function 298appeared in draft-ietf-ipngwg-rfc2292bis-01.txt, 299and was implemented in the WIDE/KAME IPv6 protocol stack kit. 300The 301.Fn iruserok_sa 302function 303appeared in discussion on the IETF ipngwg mailing list, 304and was implemented in 305.Fx 4.0 . 306