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