| .\" $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. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)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 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| rcmd, rresvport, iruserok, ruserok, rcmd_af, |
| rresvport_af, iruserok_af, ruserok_af \- routines for returning a |
| stream to a remote command |
| .SH SYNOPSIS |
| .nf |
| .B #include <netdb.h> \ \ \fP/* Or <unistd.h> on some systems */ |
| .PP |
| .BI "int rcmd(char **" ahost ", unsigned short " inport ", const char *" locuser , |
| .BI " const char *" remuser ", const char *" cmd ", int *" fd2p ); |
| .PP |
| .BI "int rresvport(int *" port ); |
| .PP |
| .BI "int iruserok(uint32_t " raddr ", int " superuser , |
| .BI " const char *" ruser ", const char *" luser ); |
| .PP |
| .BI "int ruserok(const char *" rhost ", int " superuser , |
| .BI " const char *" ruser ", const char *" luser ); |
| .PP |
| .BI "int rcmd_af(char **" ahost ", unsigned short " inport ", const char *" locuser , |
| .BI " const char *" remuser ", const char *" cmd ", int *" fd2p , |
| .BI " sa_family_t " af ); |
| .PP |
| .BI "int rresvport_af(int *" port ", sa_family_t " af ); |
| .PP |
| .BI "int iruserok_af(const void *" raddr ", int " superuser , |
| .BI " const char *" ruser ", const char *" luser \ |
| ", sa_family_t " af ); |
| .PP |
| .BI "int ruserok_af(const char *" rhost ", int " superuser , |
| .BI " const char *" ruser ", const char *" luser \ |
| ", sa_family_t " af ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR rcmd (), |
| .BR rcmd_af (), |
| .BR rresvport (), |
| .BR rresvport_af (), |
| .BR iruserok (), |
| .BR iruserok_af (), |
| .BR ruserok (), |
| .BR ruserok_af (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _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 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 |
| .BR SOCK_STREAM |
| is returned to the caller, and given to the remote |
| command as |
| .IR 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 |
| .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). |
| .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 |
| .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, 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 |
| .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. |
| .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 |
| .BR 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. |
| 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." |
| .PP |
| For information on the return from |
| .BR ruserok () |
| and |
| .BR iruserok (), |
| see above. |
| .SH VERSIONS |
| The functions |
| .BR iruserok_af (), |
| .BR rcmd_af (), |
| .BR rresvport_af (), |
| and |
| .BR ruserok_af () |
| functions are provide in glibc since version 2.2. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw27 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR rcmd (), |
| .BR rcmd_af () |
| T} Thread safety MT-Unsafe |
| T{ |
| .BR rresvport (), |
| .BR rresvport_af () |
| T} Thread safety MT-Safe |
| T{ |
| .BR iruserok (), |
| .BR ruserok (), |
| .br |
| .BR iruserok_af (), |
| .BR ruserok_af () |
| T} Thread safety MT-Safe locale |
| .TE |
| .sp 1 |
| .SH CONFORMING TO |
| Not in POSIX.1. |
| Present on the BSDs, Solaris, and many other systems. |
| These |
| functions appeared in |
| 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 version 2.12. |
| .\" 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) |