diff options
Diffstat (limited to 'man3/rcmd.3')
| -rw-r--r-- | man3/rcmd.3 | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/man3/rcmd.3 b/man3/rcmd.3 new file mode 100644 index 0000000..765e85a --- /dev/null +++ b/man3/rcmd.3 @@ -0,0 +1,305 @@ +'\" t +.\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Contributed as Linux man page by David A. Holland, 970908 +.\" I have not checked whether the Linux situation is exactly the same. +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH rcmd 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +rcmd, rresvport, iruserok, ruserok, rcmd_af, +rresvport_af, iruserok_af, ruserok_af \- routines for returning a +stream to a remote command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <netdb.h> " "/* Or <unistd.h> on some systems */" +.PP +.BI "int rcmd(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p ); +.PP +.BI "int rresvport(int *" port ); +.PP +.BI "int iruserok(uint32_t " raddr ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.BI "int ruserok(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.PP +.BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p , +.BI " sa_family_t " af ); +.PP +.BI "int rresvport_af(int *" port ", sa_family_t " af ); +.PP +.BI "int iruserok_af(const void *restrict " raddr ", int " superuser , +.BI " const char *restrict " ruser ", const char *restrict " luser , +.BI " sa_family_t " af ); +.BI "int ruserok_af(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser , +.BI " sa_family_t " af ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.PP +.BR rcmd (), +.BR rcmd_af (), +.BR rresvport (), +.BR rresvport_af (), +.BR iruserok (), +.BR iruserok_af (), +.BR ruserok (), +.BR ruserok_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.ad +.SH DESCRIPTION +The +.BR rcmd () +function is used by the superuser to execute a command on +a remote machine using an authentication scheme based +on privileged port numbers. +The +.BR rresvport () +function +returns a file descriptor to a socket +with an address in the privileged port space. +The +.BR iruserok () +and +.BR ruserok () +functions are used by servers +to authenticate clients requesting service with +.BR rcmd (). +All four functions are used by the +.BR rshd (8) +server (among others). +.SS rcmd() +The +.BR rcmd () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *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 +.IR inport . +.PP +If the connection succeeds, +a socket in the Internet domain of type +.B SOCK_STREAM +is returned to the caller, and given to the remote +command as +.I stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be set up, and a file descriptor for it will be placed +in +.IR *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 UNIX signal numbers, to be +forwarded to the process group of the command. +If +.I fd2p +is 0, then the +.I stderr +(unit 2 of the remote +command) will be made the same as the +.I 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 +.BR rshd (8). +.SS rresvport() +The +.BR rresvport () +function is used to obtain a socket with a privileged +port bound to it. +This socket is suitable for use by +.BR rcmd () +and several other functions. +Privileged ports are those in the range 0 to 1023. +Only a privileged process +(on Linux, a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace) +is allowed to bind to a privileged port. +In the glibc implementation, +this function restricts its search to the ports from 512 to 1023. +The +.I port +argument is value-result: +the value it supplies to the call is used as the starting point +for a circular search of the port range; +on (successful) return, it contains the port number that was bound to. +.\" +.SS iruserok() and ruserok() +The +.BR iruserok () +and +.BR ruserok () +functions take a remote host's IP address or name, respectively, +two usernames and a flag indicating whether the local user's +name is that of the superuser. +Then, if the user is +.I not +the superuser, it checks the +.I /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.I .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 superuser, is writable by anyone other +than the owner, or is hardlinked anywhere, the check automatically fails. +Zero is returned if the machine name is listed in the +.I hosts.equiv +file, or the host and remote username are found in the +.I .rhosts +file; otherwise +.BR iruserok () +and +.BR ruserok () +return \-1. +If the local domain (as obtained from +.BR gethostname (2)) +is the same as the remote domain, only the machine name need be specified. +.PP +If the IP address of the remote host is known, +.BR iruserok () +should be used in preference to +.BR ruserok (), +as it does not require trusting the DNS server for the remote host's domain. +.SS *_af() variants +All of the functions described above work with IPv4 +.RB ( AF_INET ) +sockets. +The "_af" variants take an extra argument that allows the +socket address family to be specified. +For these functions, the +.I af +argument can be specified as +.B AF_INET +or +.BR AF_INET6 . +In addition, +.BR rcmd_af () +supports the use of +.BR AF_UNSPEC . +.SH RETURN VALUE +The +.BR 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 +.BR rresvport () +function +returns a valid, bound socket descriptor on success. +On failure, it returns \-1 and sets +.I errno +to indicate the error. +The error code +.B EAGAIN +is overloaded to mean: "All network ports in use". +.PP +For information on the return from +.BR ruserok () +and +.BR iruserok (), +see above. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rcmd (), +.BR rcmd_af () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR rresvport (), +.BR rresvport_af () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR iruserok (), +.BR ruserok (), +.BR iruserok_af (), +.BR ruserok_af () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH STANDARDS +BSD. +.SH HISTORY +.TP +.BR iruserok_af () +.TQ +.BR rcmd_af () +.TQ +.BR rresvport_af () +.TQ +.BR ruserok_af () +glibc 2.2. +.PP +Solaris, 4.2BSD. +The "_af" variants are more recent additions, +and are not present on as wide a range of systems. +.SH BUGS +.BR iruserok () +and +.BR iruserok_af () +are declared in glibc headers only since glibc 2.12. +.\" Bug filed 25 Nov 2007: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399 +.SH SEE ALSO +.BR rlogin (1), +.BR rsh (1), +.BR rexec (3), +.BR rexecd (8), +.BR rlogind (8), +.BR rshd (8) |