man3/rcmd.3

   1 '\" t
   2 .\"     $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   8 .\"
   9 .\"     @(#)rcmd.3      8.1 (Berkeley) 6/4/93
  10 .\"
  11 .\" Contributed as Linux man page by David A. Holland, 970908
  12 .\" I have not checked whether the Linux situation is exactly the same.
  13 .\"
  14 .\" 2007-12-08, mtk, Converted from mdoc to man macros
  15 .\"
  16 .TH rcmd 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 rcmd, rresvport, iruserok, ruserok, rcmd_af,
  19 rresvport_af, iruserok_af, ruserok_af \- routines for returning a
  20 stream to a remote command
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .BR "#include <netdb.h>    " "/* Or <unistd.h> on some systems */"
  27 .PP
  28 .BI "int rcmd(char **restrict " ahost ", unsigned short " inport ,
  29 .BI "            const char *restrict " locuser ,
  30 .BI "            const char *restrict " remuser ,
  31 .BI "            const char *restrict " cmd ", int *restrict " fd2p );
  32 .PP
  33 .BI "int rresvport(int *" port );
  34 .PP
  35 .BI "int iruserok(uint32_t " raddr ", int " superuser ,
  36 .BI "            const char *" ruser ", const char *" luser );
  37 .BI "int ruserok(const char *" rhost ", int " superuser ,
  38 .BI "            const char *" ruser ", const char *" luser );
  39 .PP
  40 .BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport ,
  41 .BI "            const char *restrict " locuser ,
  42 .BI "            const char *restrict " remuser ,
  43 .BI "            const char *restrict " cmd ", int *restrict " fd2p ,
  44 .BI "            sa_family_t " af );
  45 .PP
  46 .BI "int rresvport_af(int *" port ", sa_family_t " af );
  47 .PP
  48 .BI "int iruserok_af(const void *restrict " raddr ", int " superuser ,
  49 .BI "            const char *restrict " ruser ", const char *restrict " luser ,
  50 .BI "            sa_family_t " af );
  51 .BI "int ruserok_af(const char *" rhost ", int " superuser ,
  52 .BI "            const char *" ruser ", const char *" luser ,
  53 .BI "            sa_family_t " af );
  54 .fi
  55 .PP
  56 .RS -4
  57 Feature Test Macro Requirements for glibc (see
  58 .BR feature_test_macros (7)):
  59 .RE
  60 .ad l
  61 .PP
  62 .BR rcmd (),
  63 .BR rcmd_af (),
  64 .BR rresvport (),
  65 .BR rresvport_af (),
  66 .BR iruserok (),
  67 .BR iruserok_af (),
  68 .BR ruserok (),
  69 .BR ruserok_af ():
  70 .nf
  71     Since glibc 2.19:
  72         _DEFAULT_SOURCE
  73     glibc 2.19 and earlier:
  74         _BSD_SOURCE
  75 .fi
  76 .ad
  77 .SH DESCRIPTION
  78 The
  79 .BR rcmd ()
  80 function is used by the superuser to execute a command on
  81 a remote machine using an authentication scheme based
  82 on privileged port numbers.
  83 The
  84 .BR rresvport ()
  85 function
  86 returns a file descriptor to a socket
  87 with an address in the privileged port space.
  88 The
  89 .BR iruserok ()
  90 and
  91 .BR ruserok ()
  92 functions are used by servers
  93 to authenticate clients requesting service with
  94 .BR rcmd ().
  95 All four functions are used by the
  96 .BR rshd (8)
  97 server (among others).
  98 .SS rcmd()
  99 The
 100 .BR rcmd ()
 101 function
 102 looks up the host
 103 .I *ahost
 104 using
 105 .BR gethostbyname (3),
 106 returning \-1 if the host does not exist.
 107 Otherwise,
 108 .I *ahost
 109 is set to the standard name of the host
 110 and a connection is established to a server
 111 residing at the well-known Internet port
 112 .IR inport .
 113 .PP
 114 If the connection succeeds,
 115 a socket in the Internet domain of type
 116 .B SOCK_STREAM
 117 is returned to the caller, and given to the remote
 118 command as
 119 .I stdin
 120 and
 121 .IR stdout .
 122 If
 123 .I fd2p
 124 is nonzero, then an auxiliary channel to a control
 125 process will be set up, and a file descriptor for it will be placed
 126 in
 127 .IR *fd2p .
 128 The control process will return diagnostic
 129 output from the command (unit 2) on this channel, and will also
 130 accept bytes on this channel as being UNIX signal numbers, to be
 131 forwarded to the process group of the command.
 132 If
 133 .I fd2p
 134 is 0, then the
 135 .I stderr
 136 (unit 2 of the remote
 137 command) will be made the same as the
 138 .I stdout
 139 and no
 140 provision is made for sending arbitrary signals to the remote process,
 141 although you may be able to get its attention by using out-of-band data.
 142 .PP
 143 The protocol is described in detail in
 144 .BR rshd (8).
 145 .SS rresvport()
 146 The
 147 .BR rresvport ()
 148 function is used to obtain a socket with a privileged
 149 port bound to it.
 150 This socket is suitable for use by
 151 .BR rcmd ()
 152 and several other functions.
 153 Privileged ports are those in the range 0 to 1023.
 154 Only a privileged process
 155 (on Linux, a process that has the
 156 .B CAP_NET_BIND_SERVICE
 157 capability in the user namespace governing its network namespace)
 158 is allowed to bind to a privileged port.
 159 In the glibc implementation,
 160 this function restricts its search to the ports from 512 to 1023.
 161 The
 162 .I port
 163 argument is value-result:
 164 the value it supplies to the call is used as the starting point
 165 for a circular search of the port range;
 166 on (successful) return, it contains the port number that was bound to.
 167 .\"
 168 .SS iruserok() and ruserok()
 169 The
 170 .BR iruserok ()
 171 and
 172 .BR ruserok ()
 173 functions take a remote host's IP address or name, respectively,
 174 two usernames and a flag indicating whether the local user's
 175 name is that of the superuser.
 176 Then, if the user is
 177 .I not
 178 the superuser, it checks the
 179 .I /etc/hosts.equiv
 180 file.
 181 If that lookup is not done, or is unsuccessful, the
 182 .I .rhosts
 183 in the local user's home directory is checked to see if the request for
 184 service is allowed.
 185 .PP
 186 If this file does not exist, is not a regular file, is owned by anyone
 187 other than the user or the superuser, is writable by anyone other
 188 than the owner, or is hardlinked anywhere, the check automatically fails.
 189 Zero is returned if the machine name is listed in the
 190 .I hosts.equiv
 191 file, or the host and remote username are found in the
 192 .I .rhosts
 193 file; otherwise
 194 .BR iruserok ()
 195 and
 196 .BR ruserok ()
 197 return \-1.
 198 If the local domain (as obtained from
 199 .BR gethostname (2))
 200 is the same as the remote domain, only the machine name need be specified.
 201 .PP
 202 If the IP address of the remote host is known,
 203 .BR iruserok ()
 204 should be used in preference to
 205 .BR ruserok (),
 206 as it does not require trusting the DNS server for the remote host's domain.
 207 .SS *_af() variants
 208 All of the functions described above work with IPv4
 209 .RB ( AF_INET )
 210 sockets.
 211 The "_af" variants take an extra argument that allows the
 212 socket address family to be specified.
 213 For these functions, the
 214 .I af
 215 argument can be specified as
 216 .B AF_INET
 217 or
 218 .BR AF_INET6 .
 219 In addition,
 220 .BR rcmd_af ()
 221 supports the use of
 222 .BR AF_UNSPEC .
 223 .SH RETURN VALUE
 224 The
 225 .BR rcmd ()
 226 function
 227 returns a valid socket descriptor on success.
 228 It returns \-1 on error and prints a diagnostic message on the standard error.
 229 .PP
 230 The
 231 .BR rresvport ()
 232 function
 233 returns a valid, bound socket descriptor on success.
 234 On failure, it returns \-1 and sets
 235 .I errno
 236 to indicate the error.
 237 The error code
 238 .B EAGAIN
 239 is overloaded to mean: "All network ports in use".
 240 .PP
 241 For information on the return from
 242 .BR ruserok ()
 243 and
 244 .BR iruserok (),
 245 see above.
 246 .SH ATTRIBUTES
 247 For an explanation of the terms used in this section, see
 248 .BR attributes (7).
 249 .ad l
 250 .nh
 251 .TS
 252 allbox;
 253 lbx lb lb
 254 l l l.
 255 Interface       Attribute       Value
 256 T{
 257 .BR rcmd (),
 258 .BR rcmd_af ()
 259 T}      Thread safety   MT-Unsafe
 260 T{
 261 .BR rresvport (),
 262 .BR rresvport_af ()
 263 T}      Thread safety   MT-Safe
 264 T{
 265 .BR iruserok (),
 266 .BR ruserok (),
 267 .BR iruserok_af (),
 268 .BR ruserok_af ()
 269 T}      Thread safety   MT-Safe locale
 270 .TE
 271 .hy
 272 .ad
 273 .sp 1
 274 .SH STANDARDS
 275 BSD.
 276 .SH HISTORY
 277 .TP
 278 .BR iruserok_af ()
 279 .TQ
 280 .BR rcmd_af ()
 281 .TQ
 282 .BR rresvport_af ()
 283 .TQ
 284 .BR ruserok_af ()
 285 glibc 2.2.
 286 .PP
 287 Solaris, 4.2BSD.
 288 The "_af" variants are more recent additions,
 289 and are not present on as wide a range of systems.
 290 .SH BUGS
 291 .BR iruserok ()
 292 and
 293 .BR iruserok_af ()
 294 are declared in glibc headers only since glibc 2.12.
 295 .\" Bug filed 25 Nov 2007:
 296 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399
 297 .SH SEE ALSO
 298 .BR rlogin (1),
 299 .BR rsh (1),
 300 .BR rexec (3),
 301 .BR rexecd (8),
 302 .BR rlogind (8),
 303 .BR rshd (8)