[apple/network_cmds.git] / rshd.tproj / rshd.8

.\" Copyright (c) 1983, 1989, 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.
.\"
.\"     @(#)rshd.8	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt RSHD 8
.Os BSD 4.2
.Sh NAME
.Nm rshd
.Nd remote shell server
.Sh SYNOPSIS
.Nm rshd
.Op Fl alnL
.Sh DESCRIPTION
The
.Nm rshd
server
is the server for the 
.Xr rcmd 3
routine and, consequently, for the
.Xr rsh 1
program.  The server provides remote execution facilities
with authentication based on privileged port numbers from trusted hosts.
.Pp
The
.Nm rshd
server
listens for service requests at the port indicated in
the ``cmd'' service specification; see
.Xr services 5 .
When a service request is received the following protocol
is initiated:
.Bl -enum
.It
The server checks the client's source port.
If the port is not in the range 512-1023, the server
aborts the connection.
.It
The server reads characters from the socket up
to a null (`\e0') byte.  The resultant string is
interpreted as an
.Tn ASCII
number, base 10.
.It
If the number received in step 2 is non-zero,
it is interpreted as the port number of a secondary
stream to be used for the 
.Em stderr .
A second connection is then created to the specified
port on the client's machine.  The source port of this
second connection is also in the range 512-1023.
.It
The server checks the client's source address
and requests the corresponding host name (see
.Xr gethostbyaddr 3 ,
.Xr hosts 5
and
.Xr named 8 ) .
If the hostname cannot be determined,
the dot-notation representation of the host address is used.
If the hostname is in the same domain as the server (according to
the last two components of the domain name),
or if the
.Fl a
option is given,
the addresses for the hostname are requested,
verifying that the name and address correspond.
If address verification fails, the connection is aborted
with the message, ``Host address mismatch.''
.It
A null terminated user name of at most 16 characters
is retrieved on the initial socket.  This user name
is interpreted as the user identity on the
.Em client Ns 's
machine.
.It
A null terminated user name of at most 16 characters
is retrieved on the initial socket.  This user name
is interpreted as a user identity to use on the
.Sy server Ns 's
machine.
.It
A null terminated command to be passed to a
shell is retrieved on the initial socket.  The length of
the command is limited by the upper bound on the size of
the system's argument list.  
.It
.Nm Rshd
then validates the user using
.Xr ruserok 3 ,
which uses the file
.Pa /etc/hosts.equiv
and the
.Pa .rhosts
file found in the user's home directory.  The
.Fl l
option prevents
.Xr ruserok 3
from doing any validation based on the user's ``.rhosts'' file,
unless the user is the superuser.
.It
If the file 
.Pa /etc/nologin
exists and the user is not the superuser,
the connection is closed.
.It
A null byte is returned on the initial socket
and the command line is passed to the normal login
shell of the user.  The
shell inherits the network connections established
by
.Nm rshd .
.El
.Pp
Transport-level keepalive messages are enabled unless the
.Fl n
option is present.
The use of keepalive messages allows sessions to be timed out
if the client crashes or becomes unreachable.
.Pp
The
.Fl L
option causes all successful accesses to be logged to
.Xr syslogd 8
as
.Li auth.info
messages.
.Sh DIAGNOSTICS
Except for the last one listed below,
all diagnostic messages
are returned on the initial socket,
after which any network connections are closed.
An error is indicated by a leading byte with a value of
1 (0 is returned in step 10 above upon successful completion
of all the steps prior to the execution of the login shell).
.Bl -tag -width indent
.It Sy Locuser too long.
The name of the user on the client's machine is
longer than 16 characters.
.It Sy Ruser too long.
The name of the user on the remote machine is
longer than 16 characters.
.It Sy Command too long  .
The command line passed exceeds the size of the argument
list (as configured into the system).
.It Sy Login incorrect.
No password file entry for the user name existed.
.It Sy Remote directory.
The 
.Xr chdir
command to the home directory failed.
.It Sy Permission denied.
The authentication procedure described above failed.
.It Sy Can't make pipe.
The pipe needed for the 
.Em stderr ,
wasn't created.
.It Sy Can't fork; try again. 
A
.Xr fork
by the server failed.
.It Sy <shellname>: ...
The user's login shell could not be started.  This message is returned
on the connection associated with the
.Em stderr ,
and is not preceded by a flag byte.
.El
.Sh SEE ALSO
.Xr rsh 1 ,
.Xr rcmd 3 ,
.Xr ruserok 3
.Sh BUGS
The authentication procedure used here assumes the integrity
of each client machine and the connecting medium.  This is
insecure, but is useful in an ``open'' environment.
.Pp
A facility to allow all data exchanges to be encrypted should be
present.
.Pp
A more extensible protocol (such as Telnet) should be used.
Commit	Line	Data
b7080c8e A	1	.\" Copyright (c) 1983, 1989, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)rshd.8 8.1 (Berkeley) 6/4/93
	33	.\"
	34	.Dd June 4, 1993
	35	.Dt RSHD 8
	36	.Os BSD 4.2
	37	.Sh NAME
	38	.Nm rshd
	39	.Nd remote shell server
	40	.Sh SYNOPSIS
	41	.Nm rshd
	42	.Op Fl alnL
	43	.Sh DESCRIPTION
	44	The
	45	.Nm rshd
	46	server
	47	is the server for the
	48	.Xr rcmd 3
	49	routine and, consequently, for the
	50	.Xr rsh 1
	51	program. The server provides remote execution facilities
	52	with authentication based on privileged port numbers from trusted hosts.
	53	.Pp
	54	The
	55	.Nm rshd
	56	server
	57	listens for service requests at the port indicated in
	58	the ``cmd'' service specification; see
	59	.Xr services 5 .
	60	When a service request is received the following protocol
	61	is initiated:
	62	.Bl -enum
	63	.It
	64	The server checks the client's source port.
65	If the port is not in the range 512-1023, the server
66	aborts the connection.
67	.It
68	The server reads characters from the socket up
69	to a null (`\e0') byte. The resultant string is
70	interpreted as an
71	.Tn ASCII
72	number, base 10.
73	.It
74	If the number received in step 2 is non-zero,
75	it is interpreted as the port number of a secondary
76	stream to be used for the
77	.Em stderr .
78	A second connection is then created to the specified
79	port on the client's machine. The source port of this
80	second connection is also in the range 512-1023.
81	.It
82	The server checks the client's source address
83	and requests the corresponding host name (see
84	.Xr gethostbyaddr 3 ,
85	.Xr hosts 5
86	and
87	.Xr named 8 ) .
88	If the hostname cannot be determined,
89	the dot-notation representation of the host address is used.
90	If the hostname is in the same domain as the server (according to
91	the last two components of the domain name),
92	or if the
93	.Fl a
94	option is given,
95	the addresses for the hostname are requested,
96	verifying that the name and address correspond.
97	If address verification fails, the connection is aborted
98	with the message, ``Host address mismatch.''
99	.It
100	A null terminated user name of at most 16 characters
101	is retrieved on the initial socket. This user name
102	is interpreted as the user identity on the
103	.Em client Ns 's
104	machine.
105	.It
106	A null terminated user name of at most 16 characters
107	is retrieved on the initial socket. This user name
108	is interpreted as a user identity to use on the
109	.Sy server Ns 's
110	machine.
111	.It
112	A null terminated command to be passed to a
113	shell is retrieved on the initial socket. The length of
114	the command is limited by the upper bound on the size of
115	the system's argument list.
116	.It
117	.Nm Rshd
118	then validates the user using
119	.Xr ruserok 3 ,
120	which uses the file
121	.Pa /etc/hosts.equiv
122	and the
123	.Pa .rhosts
124	file found in the user's home directory. The
125	.Fl l
126	option prevents
127	.Xr ruserok 3
128	from doing any validation based on the user's ``.rhosts'' file,
129	unless the user is the superuser.
130	.It
131	If the file
132	.Pa /etc/nologin
133	exists and the user is not the superuser,
134	the connection is closed.
135	.It
136	A null byte is returned on the initial socket
137	and the command line is passed to the normal login
138	shell of the user. The
139	shell inherits the network connections established
140	by
141	.Nm rshd .
142	.El
143	.Pp
144	Transport-level keepalive messages are enabled unless the
145	.Fl n
146	option is present.
147	The use of keepalive messages allows sessions to be timed out
148	if the client crashes or becomes unreachable.
149	.Pp
150	The
151	.Fl L
152	option causes all successful accesses to be logged to
153	.Xr syslogd 8
154	as
155	.Li auth.info
156	messages.
157	.Sh DIAGNOSTICS
158	Except for the last one listed below,
159	all diagnostic messages
160	are returned on the initial socket,
161	after which any network connections are closed.
162	An error is indicated by a leading byte with a value of
163	1 (0 is returned in step 10 above upon successful completion
164	of all the steps prior to the execution of the login shell).
165	.Bl -tag -width indent
166	.It Sy Locuser too long.
167	The name of the user on the client's machine is
168	longer than 16 characters.
169	.It Sy Ruser too long.
170	The name of the user on the remote machine is
171	longer than 16 characters.
172	.It Sy Command too long .
173	The command line passed exceeds the size of the argument
174	list (as configured into the system).
175	.It Sy Login incorrect.
176	No password file entry for the user name existed.
177	.It Sy Remote directory.
178	The
179	.Xr chdir
180	command to the home directory failed.
181	.It Sy Permission denied.
182	The authentication procedure described above failed.
183	.It Sy Can't make pipe.
184	The pipe needed for the
185	.Em stderr ,
186	wasn't created.
187	.It Sy Can't fork; try again.
188	A
189	.Xr fork
190	by the server failed.
191	.It Sy <shellname>: ...
192	The user's login shell could not be started. This message is returned
193	on the connection associated with the
194	.Em stderr ,
195	and is not preceded by a flag byte.
196	.El
197	.Sh SEE ALSO
198	.Xr rsh 1 ,
199	.Xr rcmd 3 ,
200	.Xr ruserok 3
201	.Sh BUGS
202	The authentication procedure used here assumes the integrity
203	of each client machine and the connecting medium. This is
204	insecure, but is useful in an ``open'' environment.
205	.Pp
206	A facility to allow all data exchanges to be encrypted should be
207	present.
208	.Pp
209	A more extensible protocol (such as Telnet) should be used.