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