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.\" $Id$ 34.\" 35.Dd February 15, 1996 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.Nd routines for returning a stream to a remote command 44.Sh SYNOPSIS 45.Fd #include <unistd.h> 46.Ft int 47.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 48.Ft int 49.Fn rresvport "int *port" 50.Ft int 51.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" 52.Ft int 53.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 54.Sh DESCRIPTION 55The 56.Fn rcmd 57function 58is used by the super-user to execute a command on 59a remote machine using an authentication scheme based 60on reserved port numbers. 61The 62.Fn rresvport 63function 64returns a descriptor to a socket 65with an address in the privileged port space. 66The 67.Fn ruserok 68function 69is used by servers 70to authenticate clients requesting service with 71.Fn rcmd . 72All three functions are present in the same file and are used 73by the 74.Xr rshd 8 75server (among others). 76.Pp 77The 78.Fn rcmd 79function 80looks up the host 81.Fa *ahost 82using 83.Xr gethostbyname 3 , 84returning \-1 if the host does not exist. 85Otherwise 86.Fa *ahost 87is set to the standard name of the host 88and a connection is established to a server 89residing at the well-known Internet port 90.Fa inport . 91.Pp 92If the connection succeeds, 93a socket in the Internet domain of type 94.Dv SOCK_STREAM 95is returned to the caller, and given to the remote 96command as 97.Em stdin 98and 99.Em stdout . 100If 101.Fa fd2p 102is non-zero, then an auxiliary channel to a control 103process will be set up, and a descriptor for it will be placed 104in 105.Fa *fd2p . 106The control process will return diagnostic 107output from the command (unit 2) on this channel, and will also 108accept bytes on this channel as being 109.Tn UNIX 110signal numbers, to be 111forwarded to the process group of the command. 112If 113.Fa fd2p 114is 0, then the 115.Em stderr 116(unit 2 of the remote 117command) will be made the same as the 118.Em stdout 119and no 120provision is made for sending arbitrary signals to the remote process, 121although you may be able to get its attention by using out-of-band data. 122.Pp 123The protocol is described in detail in 124.Xr rshd 8 . 125.Pp 126The 127.Fn rresvport 128function is used to obtain a socket with a privileged 129address bound to it. This socket is suitable for use 130by 131.Fn rcmd 132and several other functions. Privileged Internet ports are those 133in the range 0 to 1023. Only the super-user 134is allowed to bind an address of this sort to a socket. 135.Pp 136The 137.Fn iruserok 138and 139.Fn ruserok 140functions take a remote host's IP address or name, as returned by the 141.Xr gethostbyname 3 142routines, two user names and a flag indicating whether the local user's 143name is that of the super-user. 144Then, if the user is 145.Em NOT 146the super-user, it checks the 147.Pa /etc/hosts.equiv 148file. 149If that lookup is not done, or is unsuccessful, the 150.Pa .rhosts 151in the local user's home directory is checked to see if the request for 152service is allowed. 153.Pp 154If this file does not exist, is not a regular file, is owned by anyone 155other than the user or the super-user, or is writable by anyone other 156than the owner, the check automatically fails. 157Zero is returned if the machine name is listed in the 158.Dq Pa hosts.equiv 159file, or the host and remote user name are found in the 160.Dq Pa .rhosts 161file; otherwise 162.Fn iruserok 163and 164.Fn ruserok 165return \-1. 166If the local domain (as obtained from 167.Xr gethostname 3 ) 168is the same as the remote domain, only the machine name need be specified. 169.Pp 170The 171.Fn iruserok 172function is strongly preferred for security reasons. 173It requires trusting the local DNS at most, while the 174.Fn ruserok 175function requires trusting the entire DNS, which can be spoofed. 176.Sh DIAGNOSTICS 177The 178.Fn rcmd 179function 180returns a valid socket descriptor on success. 181It returns \-1 on error and prints a diagnostic message on the standard error. 182.Pp 183The 184.Fn rresvport 185function 186returns a valid, bound socket descriptor on success. 187It returns \-1 on error with the global value 188.Va errno 189set according to the reason for failure. 190The error code 191.Dv EAGAIN 192is overloaded to mean ``All network ports in use.'' 193.Sh SEE ALSO 194.Xr rlogin 1 , 195.Xr rsh 1 , 196.Xr intro 2 , 197.Xr rexec 3 , 198.Xr rexecd 8 , 199.Xr rlogind 8 , 200.Xr rshd 8 201.Sh HISTORY 202These 203functions appeared in 204.Bx 4.2 . 205