1.\" $NetBSD: rcmd.3,v 1.8 1995/02/25 06:20:52 cgd 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.Nd routines for returning a stream to a remote command 45.Sh SYNOPSIS 46.Fd #include <unistd.h> 47.Ft int 48.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 49.Ft int 50.Fn rresvport "int *port" 51.Ft int 52.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" 53.Ft int 54.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 55.Sh DESCRIPTION 56The 57.Fn rcmd 58function 59is used by the super-user to execute a command on 60a remote machine using an authentication scheme based 61on reserved port numbers. 62The 63.Fn rresvport 64function 65returns a descriptor to a socket 66with an address in the privileged port space. 67The 68.Fn iruserok 69and 70.Fn ruserok 71functions are used by servers 72to authenticate clients requesting service with 73.Fn rcmd . 74All four functions are present in the same file and are used 75by the 76.Xr rshd 8 77server (among others). 78.Pp 79The 80.Fn rcmd 81function 82looks up the host 83.Fa *ahost 84using 85.Xr gethostbyname 3 , 86returning \-1 if the host does not exist. 87Otherwise 88.Fa *ahost 89is set to the standard name of the host 90and a connection is established to a server 91residing at the well-known Internet port 92.Fa inport . 93.Pp 94If the connection succeeds, 95a socket in the Internet domain of type 96.Dv SOCK_STREAM 97is returned to the caller, and given to the remote 98command as 99.Em stdin 100and 101.Em stdout . 102If 103.Fa fd2p 104is non-zero, then an auxiliary channel to a control 105process will be set up, and a descriptor for it will be placed 106in 107.Fa *fd2p . 108The control process will return diagnostic 109output from the command (unit 2) on this channel, and will also 110accept bytes on this channel as being 111.Tn UNIX 112signal numbers, to be 113forwarded to the process group of the command. 114If 115.Fa fd2p 116is 0, then the 117.Em stderr 118(unit 2 of the remote 119command) will be made the same as the 120.Em stdout 121and no 122provision is made for sending arbitrary signals to the remote process, 123although you may be able to get its attention by using out-of-band data. 124.Pp 125The protocol is described in detail in 126.Xr rshd 8 . 127.Pp 128The 129.Fn rresvport 130function is used to obtain a socket with a privileged 131address bound to it. This socket is suitable for use 132by 133.Fn rcmd 134and several other functions. Privileged Internet ports are those 135in the range 0 to 1023. Only the super-user 136is allowed to bind an address of this sort to a socket. 137.Pp 138The 139.Fn iruserok 140and 141.Fn ruserok 142functions take a remote host's IP address or name, respectively, 143two user names and a flag indicating whether the local user's 144name is that of the super-user. 145Then, if the user is 146.Em NOT 147the super-user, it checks the 148.Pa /etc/hosts.equiv 149file. 150If that lookup is not done, or is unsuccessful, the 151.Pa .rhosts 152in the local user's home directory is checked to see if the request for 153service is allowed. 154.Pp 155If this file does not exist, is not a regular file, is owned by anyone 156other than the user or the super-user, or is writeable by anyone other 157than the owner, the check automatically fails. 158Zero is returned if the machine name is listed in the 159.Dq Pa hosts.equiv 160file, or the host and remote user name are found in the 161.Dq Pa .rhosts 162file; otherwise 163.Fn iruserok 164and 165.Fn ruserok 166return \-1. 167If the local domain (as obtained from 168.Xr gethostname 2 ) 169is the same as the remote domain, only the machine name need be specified. 170.Pp 171If the IP address of the remote host is known, 172.Fn iruserok 173should be used in preference to 174.Fn ruserok , 175as it does not require trusting the DNS server for the remote host's domain. 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