mirror of https://github.com/mkerrisk/man-pages
225 lines
6.8 KiB
Groff
225 lines
6.8 KiB
Groff
.\" $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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" @(#)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 2007-12-28 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
rcmd, rresvport, iruserok, ruserok \- routines for returning a
|
|
stream to a remote command
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <netdb.h> \ \ \fP/* Or <unistd.h> on some systems */
|
|
.sp
|
|
.BI "int rcmd(char **" ahost ", int " inport ", const char *" locuser ", "
|
|
.BI " const char *" remuser ", const char *" cmd ", int *" fd2p );
|
|
.sp
|
|
.BI "int rresvport(int *" port );
|
|
.sp
|
|
.BI "int iruserok(uint32_t " raddr ", int " superuser ", "
|
|
.BI " const char *" ruser ", const char *" luser );
|
|
.sp
|
|
.BI "int ruserok(const char *" rhost ", int " superuser ", "
|
|
.BI " const char *" ruser ", const char *" luser );
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR rcmd (),
|
|
.BR rresvport (),
|
|
.BR ruserok ():
|
|
_BSD_SOURCE
|
|
.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 reserved port numbers.
|
|
The
|
|
.BR rresvport ()
|
|
function
|
|
returns a 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 present in the same file and are used
|
|
by the
|
|
.BR rshd (8)
|
|
server (among others).
|
|
.PP
|
|
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
|
|
.BR SOCK_STREAM
|
|
is returned to the caller, and given to the remote
|
|
command as
|
|
.IR stdin
|
|
and
|
|
.IR stdout .
|
|
If
|
|
.I 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
|
|
.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
|
|
.IR stderr
|
|
(unit 2 of the remote
|
|
command) will be made the same as the
|
|
.IR 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).
|
|
.PP
|
|
The
|
|
.BR rresvport ()
|
|
function is used to obtain a socket with a privileged
|
|
address bound to it.
|
|
This socket is suitable for use by
|
|
.BR rcmd ()
|
|
and several other functions.
|
|
Privileged Internet ports are those in the range 0 to 1023.
|
|
Only the superuser is allowed to bind an address of this sort to a socket.
|
|
.PP
|
|
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
|
|
.IR /etc/hosts.equiv
|
|
file.
|
|
If that lookup is not done, or is unsuccessful, the
|
|
.IR .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, or is writable by anyone other
|
|
than the owner, the check automatically fails.
|
|
Zero is returned if the machine name is listed in the
|
|
.IR hosts.equiv
|
|
file, or the host and remote username are found in the
|
|
.IR .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.
|
|
.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.
|
|
It returns \-1 on error with the global value
|
|
.I errno
|
|
set according to the reason for failure.
|
|
The error code
|
|
.BR EAGAIN
|
|
is overloaded to mean "All network ports in use."
|
|
.SH "CONFORMING TO"
|
|
Not in POSIX.1-2001.
|
|
Present on the BSDs, Solaris, and many other systems.
|
|
These
|
|
functions appeared in
|
|
4.2BSD.
|
|
.SH BUGS
|
|
.BR iruserok ()
|
|
is not declared in glibc headers.
|
|
.\" Bug filed 25 Nov 2007:
|
|
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=5399
|
|
.SH SEE ALSO
|
|
.BR rlogin (1),
|
|
.BR rsh (1),
|
|
.BR intro (2),
|
|
.BR rexec (3),
|
|
.BR rexecd (8),
|
|
.BR rlogind (8),
|
|
.BR rshd (8)
|