lib/libc/net/rcmd.3

   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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)rcmd.3        8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/net/rcmd.3,v 1.27 2008/12/14 22:48:48 murray Exp $
  30 .\" $DragonFly: src/lib/libc/net/rcmd.3,v 1.4 2007/11/23 23:16:36 swildner Exp $
  31 .\"
  32 .Dd March 3, 2000
  33 .Dt RCMD 3
  34 .Os
  35 .Sh NAME
  36 .Nm rcmd ,
  37 .Nm rresvport ,
  38 .Nm iruserok ,
  39 .Nm ruserok ,
  40 .Nm rcmd_af ,
  41 .Nm rresvport_af ,
  42 .Nm iruserok_sa
  43 .Nd routines for returning a stream to a remote command
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In unistd.h
  48 .Ft int
  49 .Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
  50 .Ft int
  51 .Fn rresvport "int *port"
  52 .Ft int
  53 .Fn iruserok "u_long 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 rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
  58 .Ft int
  59 .Fn rresvport_af "int *port" "int af"
  60 .Ft int
  61 .Fn iruserok_sa "const void *addr" "int addrlen" "int superuser" "const char *ruser" "const char *luser"
  62 .Sh DESCRIPTION
  63 The
  64 .Fn rcmd
  65 function
  66 is used by the super-user to execute a command on
  67 a remote machine using an authentication scheme based
  68 on reserved port numbers.
  69 The
  70 .Fn rresvport
  71 function
  72 returns a descriptor to a socket
  73 with an address in the privileged port space.
  74 The
  75 .Fn ruserok
  76 function
  77 is used by servers
  78 to authenticate clients requesting service with
  79 .Fn rcmd .
  80 All three functions are present in the same file and are used
  81 by the
  82 .Xr rshd 8
  83 server (among others).
  84 .Pp
  85 The
  86 .Fn rcmd
  87 function
  88 looks up the host
  89 .Fa *ahost
  90 using
  91 .Xr gethostbyname 3 ,
  92 returning -1 if the host does not exist.
  93 Otherwise
  94 .Fa *ahost
  95 is set to the standard name of the host
  96 and a connection is established to a server
  97 residing at the well-known Internet port
  98 .Fa inport .
  99 .Pp
 100 If the connection succeeds,
 101 a socket in the Internet domain of type
 102 .Dv SOCK_STREAM
 103 is returned to the caller, and given to the remote
 104 command as
 105 .Dv stdin
 106 and
 107 .Dv stdout .
 108 If
 109 .Fa fd2p
 110 is non-zero, then an auxiliary channel to a control
 111 process will be set up, and a descriptor for it will be placed
 112 in
 113 .Fa *fd2p .
 114 The control process will return diagnostic
 115 output from the command (unit 2) on this channel, and will also
 116 accept bytes on this channel as being
 117 .Ux
 118 signal numbers, to be
 119 forwarded to the process group of the command.
 120 If
 121 .Fa fd2p
 122 is 0, then the
 123 .Dv stderr
 124 (unit 2 of the remote
 125 command) will be made the same as the
 126 .Dv stdout
 127 and no
 128 provision is made for sending arbitrary signals to the remote process,
 129 although you may be able to get its attention by using out-of-band data.
 130 .Pp
 131 The protocol is described in detail in
 132 .Xr rshd 8 .
 133 .Pp
 134 The
 135 .Fn rresvport
 136 function is used to obtain a socket to which an address with a Privileged
 137 Internet port is bound.
 138 This socket is suitable for use by
 139 .Fn rcmd
 140 and several other functions.
 141 Privileged Internet ports are those in the range 0 to 1023.
 142 Only the super-user is allowed to bind an address of this sort
 143 to a socket.
 144 .Pp
 145 The
 146 .Fn iruserok
 147 and
 148 .Fn ruserok
 149 functions take a remote host's IP address or name, as returned by the
 150 .Xr gethostbyname 3
 151 routines, two user names and a flag indicating whether the local user's
 152 name is that of the super-user.
 153 Then, if the user is
 154 .Em NOT
 155 the super-user, it checks the
 156 .Pa /etc/hosts.equiv
 157 file.
 158 If that lookup is not done, or is unsuccessful, the
 159 .Pa .rhosts
 160 in the local user's home directory is checked to see if the request for
 161 service is allowed.
 162 .Pp
 163 If this file does not exist, is not a regular file, is owned by anyone
 164 other than the user or the super-user, or is writable by anyone other
 165 than the owner, the check automatically fails.
 166 Zero is returned if the machine name is listed in the
 167 .Dq Pa hosts.equiv
 168 file, or the host and remote user name are found in the
 169 .Dq Pa .rhosts
 170 file; otherwise
 171 .Fn iruserok
 172 and
 173 .Fn ruserok
 174 return -1.
 175 If the local domain (as obtained from
 176 .Xr gethostname 3 )
 177 is the same as the remote domain, only the machine name need be specified.
 178 .Pp
 179 The
 180 .Fn iruserok
 181 function is strongly preferred for security reasons.
 182 It requires trusting the local DNS at most, while the
 183 .Fn ruserok
 184 function requires trusting the entire DNS, which can be spoofed.
 185 .Pp
 186 The functions with an
 187 .Dq Li _af
 188 or
 189 .Dq Li _sa
 190 suffix, i.e.,
 191 .Fn rcmd_af ,
 192 .Fn rresvport_af
 193 and
 194 .Fn iruserok_sa ,
 195 work the same as the corresponding functions without a
 196 suffix, except that they are capable of handling both IPv6 and IPv4 ports.
 197 .Pp
 198 The
 199 .Dq Li _af
 200 suffix means that the function has an additional
 201 .Fa af
 202 argument which is used to specify the address family,
 203 (see below).
 204 The
 205 .Fa af
 206 argument extension is implemented for functions
 207 that have no binary address argument.
 208 Instead, the
 209 .Fa af
 210 argument specifies which address family is desired.
 211 .Pp
 212 The
 213 .Dq Li _sa
 214 suffix means that the function has general socket address and
 215 length arguments.
 216 As the socket address is a protocol independent data structure,
 217 IPv4 and IPv6 socket address can be passed as desired.
 218 The
 219 .Fa sa
 220 argument extension is implemented for functions
 221 that pass a protocol dependent binary address argument.
 222 The argument needs to be replaced with a more general address structure
 223 to support multiple address families in a general way.
 224 .Pp
 225 The functions with neither an
 226 .Dq Li _af
 227 suffix nor an
 228 .Dq Li _sa
 229 suffix work for IPv4 only, except for
 230 .Fn ruserok
 231 which can handle both IPv6 and IPv4.
 232 To switch the address family, the
 233 .Fa af
 234 argument must be filled with
 235 .Dv AF_INET ,
 236 or
 237 .Dv AF_INET6 .
 238 For
 239 .Fn rcmd_af ,
 240 .Dv PF_UNSPEC
 241 is also allowed.
 242 .Sh ENVIRONMENT
 243 .Bl -tag -width RSH
 244 .It Ev RSH
 245 When using the
 246 .Fn rcmd
 247 function, this variable is used as the program to run instead of
 248 .Xr rsh 1 .
 249 .El
 250 .Sh DIAGNOSTICS
 251 The
 252 .Fn rcmd
 253 function
 254 returns a valid socket descriptor on success.
 255 It returns -1 on error and prints a diagnostic message
 256 on the standard error.
 257 .Pp
 258 The
 259 .Fn rresvport
 260 function
 261 returns a valid, bound socket descriptor on success.
 262 It returns -1 on error with the global value
 263 .Va errno
 264 set according to the reason for failure.
 265 The error code
 266 .Er EAGAIN
 267 is overloaded to mean ``All network ports in use.''
 268 .Sh SEE ALSO
 269 .Xr rlogin 1 ,
 270 .Xr rsh 1 ,
 271 .Xr intro 2 ,
 272 .Xr rlogind 8 ,
 273 .Xr rshd 8
 274 .Rs
 275 .%A W. Stevens
 276 .%A M. Thomas
 277 .%T "Advanced Socket API for IPv6"
 278 .%O RFC 2292
 279 .Re
 280 .Rs
 281 .%A W. Stevens
 282 .%A M. Thomas
 283 .%A E. Nordmark
 284 .%T "Advanced Socket API for IPv6"
 285 .%O RFC 3542
 286 .Re
 287 .Sh HISTORY
 288 Most of these
 289 functions appeared in
 290 .Bx 4.2 .
 291 The
 292 .Fn rresvport_af
 293 function
 294 appeared in RFC 2292, and was implemented by the WIDE project
 295 for the Hydrangea IPv6 protocol stack kit.
 296 The
 297 .Fn rcmd_af
 298 function
 299 appeared in draft-ietf-ipngwg-rfc2292bis-01.txt,
 300 and was implemented in the WIDE/KAME IPv6 protocol stack kit.
 301 The
 302 .Fn iruserok_sa
 303 function
 304 appeared in discussion on the IETF ipngwg mailing list,
 305 and was implemented in
 306 .Fx 4.0 .