diff options
Diffstat (limited to 'newlib/libc/sys/linux/net/rcmd.3')
| -rw-r--r-- | newlib/libc/sys/linux/net/rcmd.3 | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/newlib/libc/sys/linux/net/rcmd.3 b/newlib/libc/sys/linux/net/rcmd.3 new file mode 100644 index 000000000..9479a237d --- /dev/null +++ b/newlib/libc/sys/linux/net/rcmd.3 @@ -0,0 +1,298 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD: src/lib/libc/net/rcmd.3,v 1.20 2001/10/01 16:08:56 ru Exp $ +.\" +.Dd March 3, 2000 +.Dt RCMD 3 +.Os +.Sh NAME +.Nm rcmd , +.Nm rresvport , +.Nm iruserok , +.Nm ruserok , +.Nm rcmd_af , +.Nm rresvport_af , +.Nm iruserok_sa +.Nd routines for returning a stream to a remote command +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" +.Ft int +.Fn rresvport "int *port" +.Ft int +.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" +.Ft int +.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" +.Ft int +.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" +.Ft int +.Fn rresvport_af "int *port" "int af" +.Ft int +.Fn iruserok_sa "const void *addr" "int addrlen" "int superuser" "const char *ruser" "const char *luser" +.Sh DESCRIPTION +The +.Fn rcmd +function +is used by the super-user to execute a command on +a remote machine using an authentication scheme based +on reserved port numbers. +The +.Fn rresvport +function +returns a descriptor to a socket +with an address in the privileged port space. +The +.Fn ruserok +function +is used by servers +to authenticate clients requesting service with +.Fn rcmd . +All three functions are present in the same file and are used +by the +.Xr rshd 8 +server (among others). +.Pp +The +.Fn rcmd +function +looks up the host +.Fa *ahost +using +.Xr gethostbyname 3 , +returning -1 if the host does not exist. +Otherwise +.Fa *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.Fa inport . +.Pp +If the connection succeeds, +a socket in the Internet domain of type +.Dv SOCK_STREAM +is returned to the caller, and given to the remote +command as +.Em stdin +and +.Em stdout . +If +.Fa fd2p +is non-zero, then an auxiliary channel to a control +process will be set up, and a descriptor for it will be placed +in +.Fa *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being +.Tn UNIX +signal numbers, to be +forwarded to the process group of the command. +If +.Fa fd2p +is 0, then the +.Em stderr +(unit 2 of the remote +command) will be made the same as the +.Em stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.Pp +The protocol is described in detail in +.Xr rshd 8 . +.Pp +The +.Fn rresvport +function is used to obtain a socket to which an address with a Privileged +Internet port is bound. +This socket is suitable for use by +.Fn rcmd +and several other functions. +Privileged Internet ports are those in the range 0 to 1023. +Only the super-user is allowed to bind an address of this sort +to a socket. +.Pp +The +.Fn iruserok +and +.Fn ruserok +functions take a remote host's IP address or name, as returned by the +.Xr gethostbyname 3 +routines, two user names and a flag indicating whether the local user's +name is that of the super-user. +Then, if the user is +.Em NOT +the super-user, it checks the +.Pa /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.Pa .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.Pp +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the super-user, or is writable by anyone other +than the owner, the check automatically fails. +Zero is returned if the machine name is listed in the +.Dq Pa hosts.equiv +file, or the host and remote user name are found in the +.Dq Pa .rhosts +file; otherwise +.Fn iruserok +and +.Fn ruserok +return -1. +If the local domain (as obtained from +.Xr gethostname 3 ) +is the same as the remote domain, only the machine name need be specified. +.Pp +The +.Fn iruserok +function is strongly preferred for security reasons. +It requires trusting the local DNS at most, while the +.Fn ruserok +function requires trusting the entire DNS, which can be spoofed. +.Pp +The functions with an +.Dq Li _af +or +.Dq Li _sa +suffix, i.e., +.Fn rcmd_af , +.Fn rresvport_af +and +.Fn iruserok_sa , +work the same as the corresponding functions without a +suffix, except that they are capable of handling both IPv6 and IPv4 ports. +.Pp +The +.Dq Li _af +suffix means that the function has an additional +.Fa af +argument which is used to specify the address family, +(see below). +The +.Fa af +argument extension is implemented for functions +that have no binary address argument. +Instead, the +.Fa af +argument specifies which address family is desired. +.Pp +The +.Dq Li _sa +suffix means that the function has general socket address and +length arguments. +As the socket address is a protocol independent data structure, +IPv4 and IPv6 socket address can be passed as desired. +The +.Fa sa +argument extension is implemented for functions +that pass a protocol dependent binary address argument. +The argument needs to be replaced with a more general address structure +to support multiple address families in a general way. +.Pp +The functions with neither an +.Dq Li _af +suffix nor an +.Dq Li _sa +suffix work for IPv4 only, except for +.Fn ruserok +which can handle both IPv6 and IPv4. +To switch the address family, the +.Fa af +argument must be filled with +.Dv AF_INET , +or +.Dv AF_INET6 . +For +.Fn rcmd_af , +.Dv PF_UNSPEC +is also allowed. +.Sh DIAGNOSTICS +The +.Fn rcmd +function +returns a valid socket descriptor on success. +It returns -1 on error and prints a diagnostic message +on the standard error. +.Pp +The +.Fn rresvport +function +returns a valid, bound socket descriptor on success. +It returns -1 on error with the global value +.Va errno +set according to the reason for failure. +The error code +.Er EAGAIN +is overloaded to mean ``All network ports in use.'' +.Sh SEE ALSO +.Xr rlogin 1 , +.Xr rsh 1 , +.Xr intro 2 , +.Xr rexec 3 , +.Xr rexecd 8 , +.Xr rlogind 8 , +.Xr rshd 8 +.Pp +.Rs +.%A W. Stevens +.%A M. Thomas +.%T "Advanced Socket API for IPv6" +.%O RFC2292 +.Re +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%T "Advanced Socket API for IPv6" +.%O draft-ietf-ipngwg-rfc2292bis-01.txt +.Re +.Sh HISTORY +Most of these +functions appeared in +.Bx 4.2 . +.Fn rresvport_af +appeared in RFC2292, and was implemented by the WIDE project +for the Hydrangea IPv6 protocol stack kit. +.Fn rcmd_af +appeared in draft-ietf-ipngwg-rfc2292bis-01.txt, +and was implemented in the WIDE/KAME IPv6 protocol stack kit. +.Fn iruserok_sa +appeared in discussion on the IETF ipngwg mailing list, +and was implemented in +.Fx 4.0 . |