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