1.\" $NetBSD: rcmd.3,v 1.22 2002/02/07 07:00:21 ross Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd June 4, 1993 37.Dt RCMD 3 38.Os 39.Sh NAME 40.Nm rcmd , 41.Nm orcmd , 42.Nm rcmd_af , 43.Nm orcmd_af , 44.Nm rresvport , 45.Nm rresvport_af , 46.Nm iruserok , 47.Nm ruserok , 48.Nm iruserok_sa 49.Nd routines for returning a stream to a remote command 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.Fd #include \*[Lt]unistd.h\*[Gt] 54.Ft int 55.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 56.Ft int 57.Fn orcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 58.Ft int 59.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 60.Ft int 61.Fn orcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 62.Ft int 63.Fn rresvport "int *port" 64.Ft int 65.Fn rresvport_af "int *port" "int family" 66.Ft int 67.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser" 68.Ft int 69.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 70.Ft int 71.Fn iruserok_sa "const void *raddr" "int rlen" "int superuser" "const char *ruser" "const char *luser" 72.Sh DESCRIPTION 73The 74.Fn rcmd 75function is available for use by anyone to run commands on a 76remote system. It acts like the 77.Fn orcmd 78command, with the exception that it makes a call out to the 79.Xr rcmd 1 80command, or any other user-specified command, to perform the 81actual connection (thus not requiring 82that the caller be running as the super-user), and is only 83available for the 84.Dq shell/tcp 85port. 86The 87.Fn orcmd 88function 89is used by the super-user to execute a command on 90a remote machine using an authentication scheme based 91on reserved port numbers. 92While 93.Fn rcmd 94and 95.Fn orcmd 96can only handle IPv4 address in the first argument, 97.Fn rcmd_af 98and 99.Fn orcmd_af 100can handle other cases as well. 101The 102.Fn rresvport 103function 104returns a descriptor to a socket 105with an address in the privileged port space. 106The 107.Fn rresvport_af 108function is similar to 109.Fn rresvport , 110but you can explicitly specify the address family to use. 111Calling 112.Fn rresvport_af 113with 114.Dv AF_INET 115has the same effect as 116.Fn rresvport . 117The 118.Fn iruserok 119and 120.Fn ruserok 121functions are used by servers 122to authenticate clients requesting service with 123.Fn rcmd . 124All six functions are present in the same file and are used 125by the 126.Xr rshd 8 127server (among others). 128.Fn iruserok_sa 129is an address family independent variant of 130.Fn iruserok . 131.Pp 132The 133.Fn rcmd 134function 135looks up the host 136.Fa *ahost 137using 138.Xr gethostbyname 3 , 139returning \-1 if the host does not exist. 140Otherwise 141.Fa *ahost 142is set to the standard name of the host 143and a connection is established to a server 144residing at the well-known Internet port 145.Fa inport . 146.Pp 147If the connection succeeds, 148a socket in the Internet domain of type 149.Dv SOCK_STREAM 150is returned to the caller, and given to the remote 151command as 152.Em stdin 153and 154.Em stdout . 155If 156.Fa fd2p 157is non-zero, then an auxiliary channel to a control 158process will be set up, and a descriptor for it will be placed 159in 160.Fa *fd2p . 161The control process will return diagnostic 162output from the command (unit 2) on this channel, and will also 163accept bytes on this channel as being 164.Ux 165signal numbers, to be 166forwarded to the process group of the command. 167If 168.Fa fd2p 169is 0, then the 170.Em stderr 171(unit 2 of the remote 172command) will be made the same as the 173.Em stdout 174and no 175provision is made for sending arbitrary signals to the remote process, 176although you may be able to get its attention by using out-of-band data. 177.Pp 178.Fn rcmd_af 179and 180.Fn orcmd_af 181take address family in the last argument. 182If the last argument is 183.Dv PF_UNSPEC , 184interpretation of 185.Fa *ahost 186will obey the underlying address resolution like DNS. 187.Pp 188The protocol is described in detail in 189.Xr rshd 8 . 190.Pp 191The 192.Fn rresvport 193and 194.Fn rresvport_af 195functions are used to obtain a socket with a privileged 196address bound to it. This socket is suitable for use 197by 198.Fn rcmd 199and several other functions. Privileged Internet ports are those 200in the range 0 to 1023. Only the super-user 201is allowed to bind an address of this sort to a socket. 202.Pp 203The 204.Fn iruserok 205and 206.Fn ruserok 207functions take a remote host's IP address or name, respectively, 208two user names and a flag indicating whether the local user's 209name is that of the super-user. 210Then, if the user is 211.Em NOT 212the super-user, it checks the 213.Pa /etc/hosts.equiv 214file. 215If that lookup is not done, or is unsuccessful, the 216.Pa .rhosts 217in the local user's home directory is checked to see if the request for 218service is allowed. 219.Pp 220If this file does not exist, is not a regular file, is owned by anyone 221other than the user or the super-user, or is writeable by anyone other 222than the owner, the check automatically fails. 223Zero is returned if the machine name is listed in the 224.Dq Pa hosts.equiv 225file, or the host and remote user name are found in the 226.Dq Pa .rhosts 227file; otherwise 228.Fn iruserok 229and 230.Fn ruserok 231return \-1. 232If the local domain (as obtained from 233.Xr gethostname 3 ) 234is the same as the remote domain, only the machine name need be specified. 235.Pp 236If the IP address of the remote host is known, 237.Fn iruserok 238should be used in preference to 239.Fn ruserok , 240as it does not require trusting the DNS server for the remote host's domain. 241.Pp 242While 243.Fn iruserok 244can handle IPv4 addresses only, 245.Fn iruserok_sa 246and 247.Fn ruserok 248can handle other address families as well, like IPv6. 249The first argument of 250.Fn iruserok_sa 251is typed as 252.Fa "void *" 253to avoid dependency between 254.Aq Li unistd.h 255and 256.Aq Li sys/socket.h . 257.Sh ENVIRONMENT 258.Bl -tag -width RCMD_CMDxx -compact 259.It Ev RCMD_CMD 260When using the 261.Fn rcmd 262function, this variable is used as the program to run instead of 263.Xr rcmd 1 . 264.El 265.Sh DIAGNOSTICS 266The 267.Fn rcmd 268function 269returns a valid socket descriptor on success. 270It returns \-1 on error and prints a diagnostic message on the standard error. 271.Pp 272The 273.Fn rresvport 274and 275.Fn rresvport_af 276function 277return a valid, bound socket descriptor on success. 278They return \-1 on error with the global value 279.Va errno 280set according to the reason for failure. 281The error code 282.Dv EAGAIN 283is overloaded to mean ``All network ports in use.'' 284.Sh SEE ALSO 285.Xr rcmd 1 , 286.Xr rlogin 1 , 287.Xr rsh 1 , 288.Xr intro 2 , 289.Xr rexec 3 , 290.Xr hosts.equiv 5 , 291.Xr rhosts 5 , 292.Xr rexecd 8 , 293.Xr rlogind 8 , 294.Xr rshd 8 295.Sh HISTORY 296The 297.Fn orcmd , 298.Fn rresvport , 299.Fn iruserok 300and 301.Fn ruserok 302functions appeared in 303.Bx 4.2 , 304where the 305.Fn orcmd 306function was called 307.Fn rcmd . 308The (newer) 309.Fn rcmd 310function appeared in 311.Nx 1.3 . 312.Fn rcmd_af 313and 314.Fn rresvport_af 315were defined in RFC2292. 316.Sh BUGS 317As the 318.Nm 319function uses 320.Xr getpwent 3 321functions, 322passing in a previous value from one of this family of functions 323can result in unpredictable results. Do not write code like the 324following: 325.Bd -literal -offset indent 326struct passwd *pw; 327 328pw = getpwuid(getuid()); 329... 330if (rcmd(host, port, pw-\*[Gt]pw_name, pw-\*[Gt]pw_name, cmd, fd2p) \*[Lt] 0) 331 err(1, "rcmd"); 332 333.Ed 334.Pp 335When a reentrant version of 336.Xr getpwent 3 337is available, 338.Nm 339should be changed to use this instead. 340