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