1.\" $OpenBSD: rcmd.3,v 1.31 2014/04/19 18:11:19 tedu 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: April 19 2014 $ 31.Dt RCMD 3 32.Os 33.Sh NAME 34.Nm rcmd , 35.Nm rcmd_af , 36.Nm rresvport , 37.Nm rresvport_af , 38.Nm iruserok , 39.Nm ruserok , 40.Nm iruserok_sa 41.Nd routines for returning a stream to a remote command 42.Sh SYNOPSIS 43.In 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 rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 48.Ft int 49.Fn rresvport "int *port" 50.Ft int 51.Fn rresvport_af "int *port" "int af" 52.Ft int 53.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser" 54.Ft int 55.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 56.Ft int 57.Fn iruserok_sa "const void *sa" "int salen" "int superuser" "const char *ruser" "const char *luser" 58.Sh DESCRIPTION 59The 60.Fn rcmd 61function is used by the superuser to execute a command on a remote 62machine using an authentication scheme based on reserved 63port numbers. 64If the calling process is not setuid, the 65.Ev RSH 66environment variable is set, and 67.Fa inport 68is 69.Dq shell/tcp , 70.Xr rcmdsh 3 71is called instead with the value of 72.Ev RSH . 73Alternately, if the user is not the superuser, 74.Fn rcmd 75will invoke 76.Xr rcmdsh 3 77to run the command via 78.Xr ssh 1 . 79While 80.Fn rcmd 81can handle IPv4 cases only, 82the 83.Fn rcmd_af 84function can handle other cases as well. 85.Pp 86The 87.Fn rresvport 88and 89.Fn rresvport_af 90functions return a descriptor to a socket 91with an address in the privileged port space. 92The 93.Fn iruserok 94and 95.Fn ruserok 96functions are used by servers 97to authenticate clients requesting service with 98.Fn rcmd . 99.Fn iruserok_sa 100is an address family independent variant of 101.Fn iruserok . 102.Pp 103The 104.Fn rcmd 105function looks up the host 106.Fa *ahost 107using 108.Xr gethostbyname 3 , 109returning \-1 if the host does not exist. 110Otherwise 111.Fa *ahost 112is set to the standard name of the host 113and a connection is established to a server 114residing at the well-known Internet port 115.Fa inport . 116If the user is not the superuser, the only valid port is 117.Dq shell/tcp 118(usually port 514). 119.Pp 120If the connection succeeds, 121a socket in the Internet domain of type 122.Dv SOCK_STREAM 123is returned to the caller, and given to the remote 124command as stdin and stdout. 125If 126.Fa fd2p 127is non-zero, then an auxiliary channel to a control 128process will be set up, and a descriptor for it will be placed 129in 130.Fa *fd2p . 131The control process will return diagnostic 132output from the command (unit 2) on this channel, and will also 133accept bytes on this channel as being 134.Tn UNIX 135signal numbers, to be 136forwarded to the process group of the command. 137If 138.Fa fd2p 139is 140.Va NULL , 141then the standard error (unit 2 of the remote command) will be made 142the same as the standard output and no provision is made for sending 143arbitrary signals to the remote process, although you may be able to 144get its attention by using out-of-band data. 145Note that if the user is not the superuser, 146.Fa fd2p 147must be 148.Va NULL . 149.Pp 150.Fn rcmd_af 151takes address family in the last argument. 152If the last argument is 153.Dv PF_UNSPEC , 154interpretation of 155.Fa *ahost 156will obey the underlying address resolution like DNS. 157.Pp 158The 159.Fn rresvport 160and 161.Fn rresvport_af 162functions are used to obtain a socket with a privileged 163address bound to it. 164This socket is suitable for use by 165.Fn rcmd 166and several other functions. 167Privileged Internet ports are those in the range 0 to 168.Va IPPORT_RESERVED - 1 , 169which happens to be 1023. 170Only the superuser is allowed to bind an address of this sort to a socket. 171.Fn rresvport 172and 173.Fn rresvport_af 174need to be seeded with a port number; if that port 175is not available these functions will find another. 176.Pp 177The 178.Fn iruserok 179and 180.Fn ruserok 181functions take a remote host's IP address or name, respectively, 182two user names and a flag indicating whether the local user's 183name is that of the superuser. 184Then, if the user is 185.Em not 186the superuser, it checks the 187.Pa /etc/hosts.equiv 188file. 189If that lookup is not done, or is unsuccessful, the 190.Pa .rhosts 191in the local user's home directory is checked to see if the request for 192service is allowed. 193.Pp 194If this file does not exist, is not a regular file, is owned by anyone 195other than the user or the superuser, or is writeable by anyone other 196than the owner, the check automatically fails. 197Zero is returned if the machine name is listed in the 198.Pa hosts.equiv 199file, or the host and remote user name are found in the 200.Pa .rhosts 201file; otherwise 202.Fn iruserok 203and 204.Fn ruserok 205return \-1. 206If the local domain (as obtained from 207.Xr gethostname 3 ) 208is the same as the remote domain, only the machine name need be specified. 209.Pp 210If the IP address of the remote host is known, 211.Fn iruserok 212should be used in preference to 213.Fn ruserok , 214as it does not require trusting the DNS server for the remote host's domain. 215.Pp 216While 217.Fn iruserok 218can handle IPv4 addresses only, 219.Fn iruserok_sa 220and 221.Fn ruserok 222can handle other address families as well, like IPv6. 223The first argument of 224.Fn iruserok_sa 225is typed as 226.Li "void *" 227to avoid dependency between 228.In unistd.h 229and 230.In sys/socket.h . 231.Sh DIAGNOSTICS 232The 233.Fn rcmd 234function returns a valid socket descriptor on success. 235It returns \-1 on error and prints a diagnostic message on the standard error. 236.Pp 237The 238.Fn rresvport 239and 240.Fn rresvport_af 241functions return a valid, bound socket descriptor on success. 242It returns \-1 on error with the global value 243.Va errno 244set according to the reason for failure. 245The error code 246.Er EAGAIN 247is overloaded to mean 248.Dq all network ports in use . 249.Sh SEE ALSO 250.Xr ssh 1 , 251.Xr intro 2 , 252.Xr bindresvport 3 , 253.Xr bindresvport_sa 3 , 254.Xr rcmdsh 3 255.Sh HISTORY 256These 257functions appeared in 258.Bx 4.2 . 259