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