rcmd(), rresvport(), ruserok(), iruserok()

execute command on remote machine 

Function


SYNOPSIS

#include <unistd.h>

int rcmd(char **ahost, int inport, const char *locuser, const char *remuser, const char *cmd, int *fd2p);

int rresvport(int *port);

int ruserok(const char *rhost, int superuser, const char *ruser, const char *luser);

int iruserok(in_addr_t raddr, int superuser, const char *ruser, const char *luser);


DESCRIPTION

The rcmd() function is used to execute a command on a remote machine using an authentication scheme based on reserved port numbers. The rresvport() function returns a descriptor to a socket with an address in the privileged port space. The ruserok() and iuserok() functions are used by servers to authenticate the client's requesting service with rcmd().

The rcmd() function looks up the specified host using gethostbyname(), returning -1 if the host does not exist. Otherwise, the name is updated to the standard name of the host and a connection is established to a server residing at the specified well-known Internet port.

If the connection succeeds, a socket in the Internet domain of type SOCK_STREAM is returned to the caller, and given to the remote command as stdin and stdout. If fd2p is non-null, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in that location to which it refers. The control process will return diagnostic output (stderr) from the command on this channel, and also accepts bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command. The diagnostic information returned does not include remote authorization failure, as the secondary connection is set up after authorization has been verified. If fd2p is null, then the stderr of the remote command is made the same as the 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.

The rresvport() function is used to obtain a socket with a privileged address bound to it. The socket is suitable for use by rcmd() and several other functions. Privileged Internet ports are those in the range 0 to 1023. The application must pass in a pointer to a port number. The port must be in the range 512 to 1023. The system first tries to bind to that port number. If it fails, it then tries to bind to port numbers less than port until either it succeeds or port number 512 is reached. The passed-in port number is updated to indicate the last port number attempted.

The ruserok() and iuserok() functions take a remote host's name or IP address, as returned by gethostbyname(), two user names, and a flag indicating whether the local user's name is that of the super-user. Then, if the user is not the super-user, it checks the ROOTDIR/etc/hosts.equiv file. If that lookup is not done, or is unsuccessful, the .rhosts file in the local user's home directory is checked to see if the request for service is allowed.

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. ruserok() and iuserok() return successfully if the machine name is listed in the hosts.equiv file, or the host and remote user name are found in the .rhosts file, otherwise the functions return failure. If the local domain (as obtained by gethostname()) is the same as the remote domain, only the machine name need be specified.

The iuserok() function is strongly preferred for security reasons. It requires trusting the local DNS at most, while the ruserok() function requires trusting the entire DNS, which can be spoofed.


PARAMETERS

ahost 

Points to the name of the host to which the connection is made. If the connection is successful, this name is updated with the standard name for the host.

inport 

Is the Internet port number on which the connection should be attempted.

locuser 

Is the user name on the local system.

remuser 

Is the user name to use for authentication on the remote system.

cmd 

Is the command to be executed on the remote host.

fd2p 

If non-null, a second connection is made to stderr of the remote command, and the file descriptor is returned through this pointer. If null, stderr of the remote command is connected to its stdout.

port 

Points to a port number to which an attempt is made to bind. This port number is updated to specify the last port number attempted.

rhost 

Is the name of the remote host for which authentication is requested.

raddr 

Is the address of remote host for which authentication is requested.

superuser 

Is a boolean flag indicating whether the local user is to be considered the super-user.

ruser 

Is the name of the remote user.

luser 

Is the name of the local user.


RETURN VALUES

On success, rcmd() returns a file descriptor connected to stdin and stdout of the remote command. In addition, the name pointed to by ahost is updated to the standard name for the host, and if fd2p is non-null, an additional file descriptor is returned through that pointer, as described above. On failure, rcmd() prints a diagnostic message to stderr and returns -1.

On success, rresvport() returns a valid, bound socket descriptor on success. On failure, it returns -1 and sets errno to EAGAIN.

On success, ruserok() and iuserok() return 0. On failure, they return -1.


CONFORMANCE

4.4BSD


MULTITHREAD SAFETY LEVEL

Unsafe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
bind(), gethostbyname(), gethostname(), rexec(), socket()


PTC MKS Toolkit 10.4 Documentation Build 39.