1.\" $NetBSD: rcmd.3,v 1.28 2010/03/22 19:30:54 joerg 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.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd March 30, 2005 33.Dt RCMD 3 34.Os 35.Sh NAME 36.Nm rcmd , 37.Nm orcmd , 38.Nm rcmd_af , 39.Nm orcmd_af , 40.Nm rresvport , 41.Nm rresvport_af , 42.Nm iruserok , 43.Nm ruserok , 44.Nm iruserok_sa 45.Nd routines for returning a stream to a remote command 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In 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 orcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 54.Ft int 55.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 56.Ft int 57.Fn orcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" 58.Ft int 59.Fn rresvport "int *port" 60.Ft int 61.Fn rresvport_af "int *port" "int family" 62.Ft int 63.Fn iruserok "uint32_t raddr" "int superuser" "const char *ruser" "const char *luser" 64.Ft int 65.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 66.Ft int 67.Fn iruserok_sa "const void *raddr" "int rlen" "int superuser" "const char *ruser" "const char *luser" 68.Sh DESCRIPTION 69The 70.Fn rcmd 71function is available for use by anyone to run commands on a 72remote system. It acts like the 73.Fn orcmd 74command, with the exception that it makes a call out to the 75.Xr rcmd 1 76command, or any other user-specified command, to perform the 77actual connection (thus not requiring 78that the caller be running as the super-user), and is only 79available for the 80.Dq shell/tcp 81port. 82The 83.Fn orcmd 84function 85is used by the super-user to execute a command on 86a remote machine using an authentication scheme based 87on reserved port numbers. 88While 89.Fn rcmd 90and 91.Fn orcmd 92can only handle IPv4 address in the first argument, 93.Fn rcmd_af 94and 95.Fn orcmd_af 96can handle other cases as well. 97The 98.Fn rresvport 99function 100returns a descriptor to a socket 101with an address in the privileged port space. 102The 103.Fn rresvport_af 104function is similar to 105.Fn rresvport , 106but you can explicitly specify the address family to use. 107Calling 108.Fn rresvport_af 109with 110.Dv AF_INET 111has the same effect as 112.Fn rresvport . 113The 114.Fn iruserok 115and 116.Fn ruserok 117functions are used by servers 118to authenticate clients requesting service with 119.Fn rcmd . 120All six functions are present in the same file and are used 121by the 122.Xr rshd 8 123server (among others). 124.Fn iruserok_sa 125is an address family independent variant of 126.Fn iruserok . 127.Pp 128The 129.Fn rcmd 130function 131looks up the host 132.Fa *ahost 133using 134.Xr gethostbyname 3 , 135returning \-1 if the host does not exist. 136Otherwise 137.Fa *ahost 138is set to the standard name of the host 139and a connection is established to a server 140residing at the well-known Internet port 141.Fa inport . 142.Pp 143If the connection succeeds, 144a socket in the Internet domain of type 145.Dv SOCK_STREAM 146is returned to the caller, and given to the remote 147command as 148.Em stdin 149and 150.Em stdout . 151If 152.Fa fd2p 153is non-zero, then an auxiliary channel to a control 154process will be set up, and a descriptor for it will be placed 155in 156.Fa *fd2p . 157The control process will return diagnostic 158output from the command (unit 2) on this channel, and will also 159accept bytes on this channel as being 160.Ux 161signal numbers, to be 162forwarded to the process group of the command. 163If 164.Fa fd2p 165is 0, then the 166.Em stderr 167(unit 2 of the remote 168command) will be made the same as the 169.Em stdout 170and no 171provision is made for sending arbitrary signals to the remote process, 172although you may be able to get its attention by using out-of-band data. 173.Pp 174.Fn rcmd_af 175and 176.Fn orcmd_af 177take address family in the last argument. 178If the last argument is 179.Dv PF_UNSPEC , 180interpretation of 181.Fa *ahost 182will obey the underlying address resolution like DNS. 183.Pp 184The protocol is described in detail in 185.Xr rshd 8 . 186.Pp 187The 188.Fn rresvport 189and 190.Fn rresvport_af 191functions are used to obtain a socket with a privileged 192address bound to it. This socket is suitable for use 193by 194.Fn rcmd 195and several other functions. Privileged Internet ports are those 196in the range 0 to 1023. Only the super-user 197is allowed to bind an address of this sort to a socket. 198.Pp 199The 200.Fn iruserok 201and 202.Fn ruserok 203functions take a remote host's IP address or name, respectively, 204two user names and a flag indicating whether the local user's 205name is that of the super-user. 206Then, if the user is 207.Em NOT 208the super-user, it checks the 209.Pa /etc/hosts.equiv 210file. 211If that lookup is not done, or is unsuccessful, the 212.Pa .rhosts 213in the local user's home directory is checked to see if the request for 214service is allowed. 215.Pp 216If this file does not exist, is not a regular file, is owned by anyone 217other than the user or the super-user, or is writable by anyone other 218than the owner, the check automatically fails. 219Zero is returned if the machine name is listed in the 220.Dq Pa hosts.equiv 221file, or the host and remote user name are found in the 222.Dq Pa .rhosts 223file; otherwise 224.Fn iruserok 225and 226.Fn ruserok 227return \-1. 228If the local domain (as obtained from 229.Xr gethostname 3 ) 230is the same as the remote domain, only the machine name need be specified. 231.Pp 232If the IP address of the remote host is known, 233.Fn iruserok 234should be used in preference to 235.Fn ruserok , 236as it does not require trusting the DNS server for the remote host's domain. 237.Pp 238While 239.Fn iruserok 240can handle IPv4 addresses only, 241.Fn iruserok_sa 242and 243.Fn ruserok 244can handle other address families as well, like IPv6. 245The first argument of 246.Fn iruserok_sa 247is typed as 248.Fa "void *" 249to avoid dependency between 250.In unistd.h 251and 252.In sys/socket.h . 253.Sh ENVIRONMENT 254.Bl -tag -width RCMD_CMDxx -compact 255.It Ev RCMD_CMD 256When using the 257.Fn rcmd 258function, this variable is used as the program to run instead of 259.Xr rcmd 1 . 260.El 261.Sh DIAGNOSTICS 262The 263.Fn rcmd 264function 265returns a valid socket descriptor on success. 266It returns \-1 on error and prints a diagnostic message on the standard error. 267.Pp 268The 269.Fn rresvport 270and 271.Fn rresvport_af 272function 273return a valid, bound socket descriptor on success. 274They return \-1 on error with the global value 275.Va errno 276set according to the reason for failure. 277The error code 278.Dv EAGAIN 279is overloaded to mean ``All network ports in use.'' 280.Sh SEE ALSO 281.Xr rcmd 1 , 282.Xr rlogin 1 , 283.Xr rsh 1 , 284.Xr intro 2 , 285.Xr rexec 3 , 286.Xr hosts.equiv 5 , 287.Xr rhosts 5 , 288.Xr rexecd 8 , 289.Xr rlogind 8 , 290.Xr rshd 8 291.Sh HISTORY 292The 293.Fn orcmd , 294.Fn rresvport , 295.Fn iruserok 296and 297.Fn ruserok 298functions appeared in 299.Bx 4.2 , 300where the 301.Fn orcmd 302function was called 303.Fn rcmd . 304The (newer) 305.Fn rcmd 306function appeared in 307.Nx 1.3 . 308.Fn rcmd_af 309and 310.Fn rresvport_af 311were defined in RFC2292. 312