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