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.\" $FreeBSD$ 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.Nm rcmd_af , 44.Nm rresvport_af , 45.Nm iruserok_af , 46.Nm ruserok_af 47.Nd routines for returning a stream to a remote command 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 rresvport "int *port" 54.Ft int 55.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" 56.Ft int 57.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 58.Ft int 59.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 60.Ft int 61.Fn rresvport_af "int *port" "int af" 62.Ft int 63.Fn iruserok_af "void *raddr" "int superuser" "const char *ruser" "const char *luser" "int af" 64.Ft int 65.Fn ruserok_af "const char *rhost" "int superuser" "const char *ruser" "const char *luser" "int af" 66.Sh DESCRIPTION 67The 68.Fn rcmd 69function 70is used by the super-user to execute a command on 71a remote machine using an authentication scheme based 72on reserved port numbers. 73The 74.Fn rresvport 75function 76returns a descriptor to a socket 77with an address in the privileged port space. 78The 79.Fn ruserok 80function 81is used by servers 82to authenticate clients requesting service with 83.Fn rcmd . 84All three functions are present in the same file and are used 85by the 86.Xr rshd 8 87server (among others). 88.Pp 89The 90.Fn rcmd 91function 92looks up the host 93.Fa *ahost 94using 95.Xr gethostbyname 3 , 96returning \-1 if the host does not exist. 97Otherwise 98.Fa *ahost 99is set to the standard name of the host 100and a connection is established to a server 101residing at the well-known Internet port 102.Fa inport . 103.Pp 104If the connection succeeds, 105a socket in the Internet domain of type 106.Dv SOCK_STREAM 107is returned to the caller, and given to the remote 108command as 109.Em stdin 110and 111.Em stdout . 112If 113.Fa fd2p 114is non-zero, then an auxiliary channel to a control 115process will be set up, and a descriptor for it will be placed 116in 117.Fa *fd2p . 118The control process will return diagnostic 119output from the command (unit 2) on this channel, and will also 120accept bytes on this channel as being 121.Tn UNIX 122signal numbers, to be 123forwarded to the process group of the command. 124If 125.Fa fd2p 126is 0, then the 127.Em stderr 128(unit 2 of the remote 129command) will be made the same as the 130.Em stdout 131and no 132provision is made for sending arbitrary signals to the remote process, 133although you may be able to get its attention by using out-of-band data. 134.Pp 135The protocol is described in detail in 136.Xr rshd 8 . 137.Pp 138The 139.Fn rresvport 140function is used to obtain a socket with a privileged 141address bound to it. This socket is suitable for use 142by 143.Fn rcmd 144and several other functions. Privileged Internet ports are those 145in the range 0 to 1023. Only the super-user 146is allowed to bind an address of this sort to a socket. 147.Pp 148The 149.Fn iruserok 150and 151.Fn ruserok 152functions take a remote host's IP address or name, as returned by the 153.Xr gethostbyname 3 154routines, two user names and a flag indicating whether the local user's 155name is that of the super-user. 156Then, if the user is 157.Em NOT 158the super-user, it checks the 159.Pa /etc/hosts.equiv 160file. 161If that lookup is not done, or is unsuccessful, the 162.Pa .rhosts 163in the local user's home directory is checked to see if the request for 164service is allowed. 165.Pp 166If this file does not exist, is not a regular file, is owned by anyone 167other than the user or the super-user, or is writable by anyone other 168than the owner, the check automatically fails. 169Zero is returned if the machine name is listed in the 170.Dq Pa hosts.equiv 171file, or the host and remote user name are found in the 172.Dq Pa .rhosts 173file; otherwise 174.Fn iruserok 175and 176.Fn ruserok 177return \-1. 178If the local domain (as obtained from 179.Xr gethostname 3 ) 180is the same as the remote domain, only the machine name need be specified. 181.Pp 182The 183.Fn iruserok 184function is strongly preferred for security reasons. 185It requires trusting the local DNS at most, while the 186.Fn ruserok 187function requires trusting the entire DNS, which can be spoofed. 188.Pp 189Functions with ``_af'' suffix, i.e. 190.Fn rcmd_af , 191.Fn rresvport_af , 192.Fn iruserok_af 193and 194.Fn ruserok_af , 195works just as same as functions without ``_af'', and is capable of 196handling both IPv6 port and IPv4 port. 197Functions without 198.Dq Li _af 199works for IPv4 only. 200To switch address family, 201.Fa af 202argument must be filled with 203.Dv AF_INET , 204or 205.Dv AF_INET6 . 206For 207.Fn rcmd_af , 208.Dv PF_UNSPEC 209is also allowed. 210.Sh DIAGNOSTICS 211The 212.Fn rcmd 213function 214returns a valid socket descriptor on success. 215It returns \-1 on error and prints a diagnostic message on the standard error. 216.Pp 217The 218.Fn rresvport 219function 220returns a valid, bound socket descriptor on success. 221It returns \-1 on error with the global value 222.Va errno 223set according to the reason for failure. 224The error code 225.Dv EAGAIN 226is overloaded to mean ``All network ports in use.'' 227.Sh SEE ALSO 228.Xr rlogin 1 , 229.Xr rsh 1 , 230.Xr intro 2 , 231.Xr rexec 3 , 232.Xr rexecd 8 , 233.Xr rlogind 8 , 234.Xr rshd 8 235.Pp 236W. Stevens and M. Thomas, ``Advanced Socket API for IPv6,'' 237RFC2292. 238.Sh HISTORY 239These 240functions appeared in 241.Bx 4.2 . 242.Fn rresvport_af 243appeared in RFC2292, and implemented by WIDE project 244for Hydrangea IPv6 protocol stack kit. 245.Fn rcmd_af 246appeared in draft-ietf-ipngwg-rfc2292bis-01.txt, 247and implemented by WIDE/KAME IPv6 protocol stack kit. 248.Fn iruserok_af 249and 250.Fn rusreok_af 251are proposed and implemented by WIDE project 252for Hydrangea IPv6 protocol stack kit. 253