1.\" $OpenBSD: rcmd.3,v 1.34 2016/05/28 15:48:30 millert 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: May 28 2016 $ 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 ruserok 39.Nd routines for returning a stream to a remote command 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 44.Ft int 45.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 46.Ft int 47.Fn rresvport "int *port" 48.Ft int 49.Fn rresvport_af "int *port" "int af" 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 is used by the superuser to execute a command on a remote 56machine using an authentication scheme based on reserved 57port numbers. 58If the calling process is not setuid, the 59.Ev RSH 60environment variable is set, and 61.Fa inport 62is 63.Dq shell/tcp , 64.Xr rcmdsh 3 65is called instead with the value of 66.Ev RSH . 67Alternately, if the user is not the superuser, 68.Fn rcmd 69will invoke 70.Xr rcmdsh 3 71to run the command via 72.Xr ssh 1 . 73While 74.Fn rcmd 75can handle IPv4 cases only, 76the 77.Fn rcmd_af 78function can handle other cases as well. 79.Pp 80The 81.Fn rresvport 82and 83.Fn rresvport_af 84functions return a descriptor to a socket 85with an address in the privileged port space. 86The 87.Fn ruserok 88function is used by servers 89to authenticate clients requesting service with 90.Fn rcmd . 91.Pp 92The 93.Fn rcmd 94function looks up the host 95.Fa *ahost 96using 97.Xr getaddrinfo 3 98and, if the host exists, 99.Fa *ahost 100is set to the canonical name of the host. 101A connection is then established to a server 102residing at the well-known Internet port 103.Fa inport . 104If the user is not the superuser, the only valid port is 105.Dq shell/tcp 106(usually port 514). 107.Pp 108If the connection succeeds, 109a socket in the Internet domain of type 110.Dv SOCK_STREAM 111is returned to the caller, and given to the remote 112command as stdin and stdout. 113If 114.Fa fd2p 115is non-zero, then an auxiliary channel to a control 116process will be set up, and a descriptor for it will be placed 117in 118.Fa *fd2p . 119The control process will return diagnostic 120output from the command (unit 2) on this channel, and will also 121accept bytes on this channel as being 122.Tn UNIX 123signal numbers, to be 124forwarded to the process group of the command. 125If 126.Fa fd2p 127is 128.Va NULL , 129then the standard error (unit 2 of the remote command) will be made 130the same as the standard output and no provision is made for sending 131arbitrary signals to the remote process, although you may be able to 132get its attention by using out-of-band data. 133Note that if the user is not the superuser, 134.Fa fd2p 135must be 136.Va NULL . 137.Pp 138.Fn rcmd_af 139takes address family in the last argument. 140If the last argument is 141.Dv AF_UNSPEC , 142interpretation of 143.Fa *ahost 144will obey the underlying address resolution like DNS. 145.Pp 146The 147.Fn rresvport 148and 149.Fn rresvport_af 150functions are used to obtain a socket with a privileged 151address bound to it. 152This socket is suitable for use by 153.Fn rcmd 154and several other functions. 155Privileged Internet ports are those in the range 0 to 156.Va IPPORT_RESERVED - 1 , 157which happens to be 1023. 158Only the superuser is allowed to bind an address of this sort to a socket. 159.Fn rresvport 160and 161.Fn rresvport_af 162need to be seeded with a port number; if that port 163is not available these functions will find another. 164.Pp 165The 166.Fn ruserok 167function takes a remote host's name, two user names, 168and a flag indicating whether the local user's 169name is that of the superuser. 170Then, if the user is 171.Em not 172the superuser, it checks the 173.Pa /etc/hosts.equiv 174file. 175If that lookup is not done, or is unsuccessful, the 176.Pa .rhosts 177in the local user's home directory is checked to see if the request for 178service is allowed. 179.Pp 180If this file does not exist, is not a regular file, is owned by anyone 181other than the user or the superuser, or is writeable by anyone other 182than the owner, the check automatically fails. 183Zero is returned if the machine name is listed in the 184.Pa hosts.equiv 185file, or the host and remote user name are found in the 186.Pa .rhosts 187file; otherwise 188.Fn ruserok 189returns \-1. 190If the local domain (as obtained from 191.Xr getaddrinfo 3 ) 192is the same as the remote domain, only the machine name need be specified. 193.Pp 194.Fn ruserok 195implicitly requires trusting the DNS server for the remote host's domain. 196.Sh DIAGNOSTICS 197The 198.Fn rcmd 199function returns a valid socket descriptor on success. 200It returns \-1 on error and prints a diagnostic message on the standard error. 201.Pp 202The 203.Fn rresvport 204and 205.Fn rresvport_af 206functions return a valid, bound socket descriptor on success. 207It returns \-1 on error with the global value 208.Va errno 209set according to the reason for failure. 210The error code 211.Er EAGAIN 212is overloaded to mean 213.Dq all network ports in use . 214.Sh SEE ALSO 215.Xr ssh 1 , 216.Xr intro 2 , 217.Xr bindresvport 3 , 218.Xr bindresvport_sa 3 , 219.Xr rcmdsh 3 220.Sh HISTORY 221These 222functions appeared in 223.Bx 4.2 . 224.Pp 225The 226.Fn iruserok 227and 228.Fn iruserok_sa 229functions, IP address based versions of 230.Fn ruserok , 231were removed in 232.Ox 6.0 . 233