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 BSD 4.2 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.Fd #include <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 . 102It is up to the caller to free the memory associated with 103.Fa *ahost 104using 105.Fn free . 106.Pp 107If the connection succeeds, 108a socket in the Internet domain of type 109.Dv SOCK_STREAM 110is returned to the caller, and given to the remote 111command as 112.Em stdin 113and 114.Em stdout . 115If 116.Fa fd2p 117is non-zero, then an auxiliary channel to a control 118process will be set up, and a descriptor for it will be placed 119in 120.Fa *fd2p . 121The control process will return diagnostic 122output from the command (unit 2) on this channel, and will also 123accept bytes on this channel as being 124.Tn UNIX 125signal numbers, to be 126forwarded to the process group of the command. 127If 128.Fa fd2p 129is 0, then the 130.Em stderr 131(unit 2 of the remote 132command) will be made the same as the 133.Em stdout 134and no 135provision is made for sending arbitrary signals to the remote process, 136although you may be able to get its attention by using out-of-band data. 137.Pp 138The protocol is described in detail in 139.Xr rshd 8 . 140.Pp 141The 142.Fn rresvport 143function is used to obtain a socket to which an address with a Privileged 144Internet port is bound. 145This socket is suitable for use by 146.Fn rcmd 147and several other functions. 148Privileged Internet ports are those in the range 0 to 1023. 149Only the super-user is allowed to bind an address of this sort 150to a socket. 151.Pp 152The 153.Fn iruserok 154and 155.Fn ruserok 156functions take a remote host's IP address or name, as returned by the 157.Xr gethostbyname 3 158routines, two user names and a flag indicating whether the local user's 159name is that of the super-user. 160Then, if the user is 161.Em NOT 162the super-user, it checks the 163.Pa /etc/hosts.equiv 164file. 165If that lookup is not done, or is unsuccessful, the 166.Pa .rhosts 167in the local user's home directory is checked to see if the request for 168service is allowed. 169.Pp 170If this file does not exist, is not a regular file, is owned by anyone 171other than the user or the super-user, or is writable by anyone other 172than the owner, the check automatically fails. 173Zero is returned if the machine name is listed in the 174.Dq Pa hosts.equiv 175file, or the host and remote user name are found in the 176.Dq Pa .rhosts 177file; otherwise 178.Fn iruserok 179and 180.Fn ruserok 181return -1. 182If the local domain (as obtained from 183.Xr gethostname 3 ) 184is the same as the remote domain, only the machine name need be specified. 185.Pp 186The 187.Fn iruserok 188function is strongly preferred for security reasons. 189It requires trusting the local DNS at most, while the 190.Fn ruserok 191function requires trusting the entire DNS, which can be spoofed. 192.Pp 193The functions with an 194.Dq Li _af 195or 196.Dq Li _sa 197suffix, i.e., 198.Fn rcmd_af , 199.Fn rresvport_af 200and 201.Fn iruserok_sa , 202work the same as the corresponding functions without a 203suffix, except that they are capable of handling both IPv6 and IPv4 ports. 204.Pp 205The 206.Dq Li _af 207suffix means that the function has an additional 208.Fa af 209argument which is used to specify the address family, 210(see below). 211The 212.Fa af 213argument extension is implemented for functions 214that have no binary address argument. 215Instead, the 216.Fa af 217argument specifies which address family is desired. 218.Pp 219The 220.Dq Li _sa 221suffix means that the function has general socket address and 222length arguments. 223As the socket address is a protocol independent data structure, 224IPv4 and IPv6 socket address can be passed as desired. 225The 226.Fa sa 227argument extension is implemented for functions 228that pass a protocol dependent binary address argument. 229The argument needs to be replaced with a more general address structure 230to support multiple address families in a general way. 231.Pp 232The functions with neither an 233.Dq Li _af 234suffix nor an 235.Dq Li _sa 236suffix work for IPv4 only, except for 237.Fn ruserok 238which can handle both IPv6 and IPv4. 239To switch the address family, the 240.Fa af 241argument must be filled with 242.Dv AF_INET , 243or 244.Dv AF_INET6 . 245For 246.Fn rcmd_af , 247.Dv PF_UNSPEC 248is also allowed. 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.Dv 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 free 3 , 272.Xr rexec 3 , 273.Xr rexecd 8 , 274.Xr rlogind 8 , 275.Xr rshd 8 276.Pp 277.Rs 278.%A W. Stevens 279.%A M. Thomas 280.%T "Advanced Socket API for IPv6" 281.%O RFC2292 282.Re 283.Rs 284.%A W. Stevens 285.%A M. Thomas 286.%A E. Nordmark 287.%T "Advanced Socket API for IPv6" 288.%O draft-ietf-ipngwg-rfc2292bis-01.txt 289.Re 290.Sh HISTORY 291Most of these 292functions appeared in 293.Bx 4.2 . 294.Fn rresvport_af 295appeared in RFC2292, and was implemented by the WIDE project 296for the Hydrangea IPv6 protocol stack kit. 297.Fn rcmd_af 298appeared in draft-ietf-ipngwg-rfc2292bis-01.txt, 299and was implemented in the WIDE/KAME IPv6 protocol stack kit. 300.Fn iruserok_sa 301appeared in discussion on the IETF ipngwg mailing list, 302and was implemented in 303.Fx 4.0 . 304