1.\" $NetBSD: rcmd.3,v 1.14 1997/11/26 18:06:54 tv 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 BSD 4.2 39.Sh NAME 40.Nm rcmd , 41.Nm rresvport , 42.Nm iruserok , 43.Nm ruserok , 44.Nm orcmd 45.Nd routines for returning a stream to a remote command 46.Sh SYNOPSIS 47.Fd #include <unistd.h> 48.Ft int 49.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 50.Ft int 51.Fn orcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 52.Ft int 53.Fn rresvport "int *port" 54.Ft int 55.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser" 56.Ft int 57.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 58.Sh DESCRIPTION 59The 60.Fn rcmd 61function is available for use by anyone to run commands on a 62remote system. It acts like the 63.Fn orcmd 64command, with the exception that it makes a call out to the 65.Xr rcmd 1 66command, or any other user-specified command, to perform the 67actual connection (thus not requiring 68that the caller be running as the super-user), and is only 69available for the 70.Dq shell/tcp 71port. 72The 73.Fn orcmd 74function 75is used by the super-user to execute a command on 76a remote machine using an authentication scheme based 77on reserved port numbers. 78The 79.Fn rresvport 80function 81returns a descriptor to a socket 82with an address in the privileged port space. 83The 84.Fn iruserok 85and 86.Fn ruserok 87functions are used by servers 88to authenticate clients requesting service with 89.Fn rcmd . 90All five functions are present in the same file and are used 91by the 92.Xr rshd 8 93server (among others). 94.Pp 95The 96.Fn rcmd 97function 98looks up the host 99.Fa *ahost 100using 101.Xr gethostbyname 3 , 102returning \-1 if the host does not exist. 103Otherwise 104.Fa *ahost 105is set to the standard name of the host 106and a connection is established to a server 107residing at the well-known Internet port 108.Fa inport . 109.Pp 110If the connection succeeds, 111a socket in the Internet domain of type 112.Dv SOCK_STREAM 113is returned to the caller, and given to the remote 114command as 115.Em stdin 116and 117.Em stdout . 118If 119.Fa fd2p 120is non-zero, then an auxiliary channel to a control 121process will be set up, and a descriptor for it will be placed 122in 123.Fa *fd2p . 124The control process will return diagnostic 125output from the command (unit 2) on this channel, and will also 126accept bytes on this channel as being 127.Tn UNIX 128signal numbers, to be 129forwarded to the process group of the command. 130If 131.Fa fd2p 132is 0, then the 133.Em stderr 134(unit 2 of the remote 135command) will be made the same as the 136.Em stdout 137and no 138provision is made for sending arbitrary signals to the remote process, 139although you may be able to get its attention by using out-of-band data. 140.Pp 141The protocol is described in detail in 142.Xr rshd 8 . 143.Pp 144The 145.Fn rresvport 146function is used to obtain a socket with a privileged 147address bound to it. This socket is suitable for use 148by 149.Fn rcmd 150and several other functions. Privileged Internet ports are those 151in the range 0 to 1023. Only the super-user 152is allowed to bind an address of this sort to a socket. 153.Pp 154The 155.Fn iruserok 156and 157.Fn ruserok 158functions take a remote host's IP address or name, respectively, 159two user names and a flag indicating whether the local user's 160name is that of the super-user. 161Then, if the user is 162.Em NOT 163the super-user, it checks the 164.Pa /etc/hosts.equiv 165file. 166If that lookup is not done, or is unsuccessful, the 167.Pa .rhosts 168in the local user's home directory is checked to see if the request for 169service is allowed. 170.Pp 171If this file does not exist, is not a regular file, is owned by anyone 172other than the user or the super-user, or is writeable by anyone other 173than the owner, the check automatically fails. 174Zero is returned if the machine name is listed in the 175.Dq Pa hosts.equiv 176file, or the host and remote user name are found in the 177.Dq Pa .rhosts 178file; otherwise 179.Fn iruserok 180and 181.Fn ruserok 182return \-1. 183If the local domain (as obtained from 184.Xr gethostname 3 ) 185is the same as the remote domain, only the machine name need be specified. 186.Pp 187If the IP address of the remote host is known, 188.Fn iruserok 189should be used in preference to 190.Fn ruserok , 191as it does not require trusting the DNS server for the remote host's domain. 192.Sh DIAGNOSTICS 193The 194.Fn rcmd 195function 196returns a valid socket descriptor on success. 197It returns \-1 on error and prints a diagnostic message on the standard error. 198.Pp 199The 200.Fn rresvport 201function 202returns a valid, bound socket descriptor on success. 203It returns \-1 on error with the global value 204.Va errno 205set according to the reason for failure. 206The error code 207.Dv EAGAIN 208is overloaded to mean ``All network ports in use.'' 209.Sh ENVIRONMENT 210.Bl -tag -width RCMD_CMDxx -compact 211.It Ev RCMD_CMD 212When using the 213.Fn rcmd 214function, this variable is used as the program to run instead of 215.Xr rcmd 1 . 216.El 217.Sh SEE ALSO 218.Xr rcmd 1 , 219.Xr rlogin 1 , 220.Xr rsh 1 , 221.Xr intro 2 , 222.Xr rexec 3 , 223.Xr hosts.equiv 5 , 224.Xr rhosts 5 , 225.Xr rexecd 8 , 226.Xr rlogind 8 , 227.Xr rshd 8 . 228.Sh HISTORY 229The 230.Fn orcmd , 231.Fn rresvport , 232.Fn iruserok 233and 234.Fn ruserok 235functions appeared in 236.Bx 4.2 , 237where the 238.Fn orcmd 239function was called 240.Fn rcmd. 241The (newer) 242.Fn rcmd 243function appeared in 244.Nx 1.3 . 245.Sh BUGS 246As the 247.Nm 248function uses 249.Xr getpwent 3 250functions, 251passing in a previous value from one of this family of functions 252can result in unpredictable results. Do not write code like the 253following: 254.Bd -literal -offset indent 255struct passwd *pw; 256 257pw = getpwuid(getuid()); 258... 259if (rcmd(host, port, pw->pw_name, pw->pw_name, cmd, fd2p) < 0) 260 err(1, "rcmd"); 261 262.Ed 263.Pp 264When a reentrant version of 265.Xr getpwent 3 266is available, 267.Nm 268should be changed to use this instead. 269