rshd -- remote shell service

SYNOPSIS

rshd [-install] [-remove] [-debug]

rshd provides remote execution facilities with authentication based on privileged port numbers from trusted hosts. Like any other 10/2016/2019/11/2022/2025 service, you can use the service utility to start and stop rshd.

rshd listens for service requests at port 514. When a service request is received, the following protocol is initiated:

The service checks the client's source port. If the port is not in the range 512-1023 then the service aborts the connection.

The service reads characters from the socket up to a NUL byte. The resultant string is interpreted as an ASCII number, base 10.

If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary stream to be used for stderr. If the port is not in the range 512-1023 then the service aborts the connection. A second connection is then created to the specified port on the client's machine.

A NUL terminated user name of at most 256 characters is retrieved on the initial socket. This is the user name (also known as remuser) on the client machine.

A NUL terminated user name of at most 256 characters is retrieved on the initial socket. This is the user name (also known as locuser on the machine running the rshd service

A NUL terminated command to be passed to a shell is retrieved on the initial socket. The length of the command is limited to 8192 bytes.

rshd then attempts to retrieve the user's password from the LSA database (see the rsetup reference page). If this fails the connection is aborted with a diagnostic message returned.

rshd then validates the user as is done at login time. If this fails the connection is aborted with a diagnostic message returned.

rshd then validates the host/client user name by checking the ROOTDIR/etc/hosts.equiv and ~/.rhosts files. If this fails the connection is aborted and a diagnostic message is returned.

A NUL byte is returned on the initial socket.

rshd loads the user's profile and runs the command specified in the user's home directory. rshd first checks to see if the SHELL environment variable is set and if so, that shell is used to run the command. If SHELL is not set, rshd checks the shell, COMSPEC, and ComSpec environment variables (in that order) to find the shell to be used. If none of these environment variables are defined, the command is run using the cmd.exe command interpreter located in the system directory.

rshd defaults to allowing multiple concurrent connections. To limit rshd to allowing only one connection at a time, use rconfig or the rshd tab of the MKS Toolkit control panel applet.

Note:: This setting is overridden by the MKS Toolkit license. The normal MKS Toolkit license limits you to a single concurrent connection. However, a license for an unlimited number of connections is available for purchase from MKS.

By default, rshd writes only errors to the event log. To have rshd also write event log entries stating remote host, local user, and command, use rconfig or the rshd tab of the MKS Toolkit control panel applet.

Also, by default, rshd fails when the local user does not exist. You can use rconfig or the rshd tab of the MKS Toolkit control panel applet to have rshd attempt to connect as a domain user when the local user does not exist.

Options

-install

installs and starts the rshd service. To start the service without installing it, use the service command:

service start rshd

-remove

stops and removes the rshd service. To stop the service without removing it, use the service command:

service stop rshd

-debug

runs rshd as a normal program in the current console for debugging purposes.

To use this option, you require the following privileges:

Replace a process level token   (SeAssignPrimaryTokenPrivilege)
Increase quotas   (SeIncreaseQuotaPrivilege)
Act as part of the operating system   (SeTcbPrivilege)

If you are lacking any of these privileges, rshd reports which are missing. You can use priv to add these privileges and then log out and back in. For example, the following assigns all three privileges required for using this option:

priv -a SeAssignPrimaryTokenPrivilege
priv -a SeIncreaseQuotaPrivilege
priv -a SeTcbPrivilege

ENVIRONMENT VARIABLES

TK_RETRY_ON_WSAENOTSOCK

When this environment varible is set, the rsh, rcp, rexec, and rlogin utilities retry up to five times if they get the WSAENOTSOCK error. The WSAENOTSOCK error is reported as:

An operation was attempted on something that is not a socket

FILES

mksmsg.dll: is required for event log support.
ROOTDIR/etc/hosts.equiv: global trusted host-user pairs list.
~/.rhosts: per-user trusted host-user pairs list.

DIAGNOSTICS

Possible exit status values are:

0: Successful completion.
>0: An error occurred.

NOTES

There is a very brief period of time when rshd is establishing a connection with a client that it is unavailable to establish a new connection with another client. Up to a limited number of connection attempts from other clients are buffered until rshd is free to service one of them. Additional connection attempts beyond that limit fail. An error results from the client indicating that it was unable to find the rshd service. In real world usage, this limitation is unlikely to be encountered. This limit is operating system dependent.

The rshd service runs programs in the home directory of the user that the client connects as. The home directory is the value of the HOME environment variable for that user. By default, this variable is set to %HOMEDRIVE%%HOMEPATH%. However, the HOMEDRIVE and HOMEPATH environment variables are only available to interactive applications and, thus, not available to services. For this reason, it is recommended that the HOME environment variable be explicitly set (without using HOMEDRIVE or HOMEPATH) for each user that rshd can be run as. For instructions on setting and viewing environment variables, see your Operating System's online help.

ACKNOWLEDGEMENT

This product includes software developed by the University of California, Berkeley and its contributors.

PORTABILITY

All UNIX systems. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. Windows Server 2025.

AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
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

rshd
remote shell service

Service