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