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