View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.net.bsd;
19  
20  import java.io.IOException;
21  import java.io.InputStream;
22  import java.net.BindException;
23  import java.net.InetAddress;
24  import java.net.ServerSocket;
25  import java.net.Socket;
26  import java.net.SocketException;
27  import java.net.UnknownHostException;
28  import java.nio.charset.StandardCharsets;
29  
30  import org.apache.commons.net.io.SocketInputStream;
31  
32  /**
33   * RCommandClient is very similar to {@link org.apache.commons.net.bsd.RExecClient}, from which it is derived, and implements the rcmd() facility that first
34   * appeared in 4.2BSD Unix. rcmd() is the facility used by the rsh (rshell) and other commands to execute a command on another machine from a trusted host
35   * without issuing a password. The trust relationship between two machines is established by the contents of a machine's /etc/hosts.equiv file and a user's
36   * .rhosts file. These files specify from which hosts and accounts on those hosts rcmd() requests will be accepted. The only additional measure for establishing
37   * trust is that all client connections must originate from a port between 512 and 1023. Consequently, there is an upper limit to the number of rcmd connections
38   * that can be running simultaneously. The required ports are reserved ports on Unix systems, and can only be bound by a process running with root permissions
39   * (to accomplish this rsh, rlogin, and related commands usualy have the suid bit set). Therefore, on a Unix system, you will only be able to successfully use
40   * the RCommandClient class if the process runs as root. However, there is no such restriction on Windows95 and some other systems. The security risks are
41   * obvious. However, when carefully used, rcmd() can be very useful when used behind a firewall.
42   * <p>
43   * As with virtually all of the client classes in org.apache.commons.net, this class derives from SocketClient. But it overrides most of its connection methods
44   * so that the local Socket will originate from an acceptable rshell port. The way to use RCommandClient is to first connect to the server, call the
45   * {@link #rcommand rcommand() } method, and then fetch the connection's input, output, and optionally error streams. Interaction with the remote command is
46   * controlled entirely through the I/O streams. Once you have finished processing the streams, you should invoke
47   * {@link org.apache.commons.net.bsd.RExecClient#disconnect disconnect() } to clean up properly.
48   * <p>
49   * By default the standard output and standard error streams of the remote process are transmitted over the same connection, readable from the input stream
50   * returned by {@link org.apache.commons.net.bsd.RExecClient#getInputStream getInputStream() } . However, it is possible to tell the rshd daemon to return the
51   * standard error stream over a separate connection, readable from the input stream returned by {@link org.apache.commons.net.bsd.RExecClient#getErrorStream
52   * getErrorStream() } . You can specify that a separate connection should be created for standard error by setting the boolean
53   * <code> separateErrorStream </code> parameter of {@link #rcommand rcommand() } to <code> true </code>. The standard input of the remote process can be written
54   * to through the output stream returned by {@link org.apache.commons.net.bsd.RExecClient#getOutputStream getOutputStream() } .
55   *
56   * @see org.apache.commons.net.SocketClient
57   * @see RExecClient
58   * @see RLoginClient
59   */
60  
61  public class RCommandClient extends RExecClient {
62      /**
63       * The default rshell port. Set to 514 in BSD Unix.
64       */
65      public static final int DEFAULT_PORT = 514;
66  
67      /**
68       * The smallest port number an rcmd client may use. By BSD convention this number is 512.
69       */
70      public static final int MIN_CLIENT_PORT = 512;
71  
72      /**
73       * The largest port number an rcmd client may use. By BSD convention this number is 1023.
74       */
75      public static final int MAX_CLIENT_PORT = 1023;
76  
77      /**
78       * The default RCommandClient constructor. Initializes the default port to <code> DEFAULT_PORT </code>.
79       */
80      public RCommandClient() {
81          setDefaultPort(DEFAULT_PORT);
82      }
83  
84      /**
85       * Opens a Socket connected to a remote host at the specified port and originating from the current host at a port in a range acceptable to the BSD rshell
86       * daemon. Before returning, {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection initialization
87       * actions.
88       *
89       * @param host The remote host.
90       * @param port The port to connect to on the remote host.
91       * @throws SocketException If the socket timeout could not be set.
92       * @throws BindException   If all acceptable rshell ports are in use.
93       * @throws IOException     If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from
94       *                         it.
95       */
96      @Override
97      public void connect(final InetAddress host, final int port) throws SocketException, IOException {
98          connect(host, port, InetAddress.getLocalHost());
99      }
100 
101     /**
102      * Opens a Socket connected to a remote host at the specified port and originating from the specified local address using a port in a range acceptable to
103      * the BSD rshell daemon. Before returning, {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection
104      * initialization actions.
105      *
106      * @param host      The remote host.
107      * @param port      The port to connect to on the remote host.
108      * @param localAddr The local address to use.
109      * @throws SocketException If the socket timeout could not be set.
110      * @throws BindException   If all acceptable rshell ports are in use.
111      * @throws IOException     If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from
112      *                         it.
113      */
114     public void connect(final InetAddress host, final int port, final InetAddress localAddr) throws SocketException, BindException, IOException {
115         int localPort;
116 
117         localPort = MAX_CLIENT_PORT;
118 
119         for (localPort = MAX_CLIENT_PORT; localPort >= MIN_CLIENT_PORT; --localPort) {
120             try {
121                 _socket_ = _socketFactory_.createSocket(host, port, localAddr, localPort);
122             } catch (final SocketException e) {
123                 continue;
124             }
125             break;
126         }
127 
128         if (localPort < MIN_CLIENT_PORT) {
129             throw new BindException("All ports in use or insufficient permssion.");
130         }
131 
132         _connectAction_();
133     }
134 
135     /**
136      * Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port. The local port must lie
137      * between <code> MIN_CLIENT_PORT </code> and <code> MAX_CLIENT_PORT </code> or an IllegalArgumentException will be thrown. Before returning,
138      * {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection initialization actions.
139      *
140      * @param host      The remote host.
141      * @param port      The port to connect to on the remote host.
142      * @param localAddr The local address to use.
143      * @param localPort The local port to use.
144      * @throws SocketException          If the socket timeout could not be set.
145      * @throws IOException              If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is
146      *                                  derived from it.
147      * @throws IllegalArgumentException If an invalid local port number is specified.
148      */
149     @Override
150     public void connect(final InetAddress host, final int port, final InetAddress localAddr, final int localPort)
151             throws SocketException, IOException, IllegalArgumentException {
152         if (localPort < MIN_CLIENT_PORT || localPort > MAX_CLIENT_PORT) {
153             throw new IllegalArgumentException("Invalid port number " + localPort);
154         }
155         super.connect(host, port, localAddr, localPort);
156     }
157 
158     /**
159      * Opens a Socket connected to a remote host at the specified port and originating from the current host at a port in a range acceptable to the BSD rshell
160      * daemon. Before returning, {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection initialization
161      * actions.
162      *
163      * @param hostname The name of the remote host.
164      * @param port     The port to connect to on the remote host.
165      * @throws SocketException      If the socket timeout could not be set.
166      * @throws BindException        If all acceptable rshell ports are in use.
167      * @throws IOException          If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived
168      *                              from it.
169      * @throws UnknownHostException If the hostname cannot be resolved.
170      */
171     @Override
172     public void connect(final String hostname, final int port) throws SocketException, IOException, UnknownHostException {
173         connect(InetAddress.getByName(hostname), port, InetAddress.getLocalHost());
174     }
175 
176     /**
177      * Opens a Socket connected to a remote host at the specified port and originating from the specified local address using a port in a range acceptable to
178      * the BSD rshell daemon. Before returning, {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection
179      * initialization actions.
180      *
181      * @param hostname  The remote host.
182      * @param port      The port to connect to on the remote host.
183      * @param localAddr The local address to use.
184      * @throws SocketException If the socket timeout could not be set.
185      * @throws BindException   If all acceptable rshell ports are in use.
186      * @throws IOException     If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from
187      *                         it.
188      */
189     public void connect(final String hostname, final int port, final InetAddress localAddr) throws SocketException, IOException {
190         connect(InetAddress.getByName(hostname), port, localAddr);
191     }
192 
193     /**
194      * Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port. The local port must lie
195      * between <code> MIN_CLIENT_PORT </code> and <code> MAX_CLIENT_PORT </code> or an IllegalArgumentException will be thrown. Before returning,
196      * {@link org.apache.commons.net.SocketClient#_connectAction_ _connectAction_() } is called to perform connection initialization actions.
197      *
198      * @param hostname  The name of the remote host.
199      * @param port      The port to connect to on the remote host.
200      * @param localAddr The local address to use.
201      * @param localPort The local port to use.
202      * @throws SocketException          If the socket timeout could not be set.
203      * @throws IOException              If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is
204      *                                  derived from it.
205      * @throws UnknownHostException     If the hostname cannot be resolved.
206      * @throws IllegalArgumentException If an invalid local port number is specified.
207      */
208     @Override
209     public void connect(final String hostname, final int port, final InetAddress localAddr, final int localPort)
210             throws SocketException, IOException, IllegalArgumentException, UnknownHostException {
211         if (localPort < MIN_CLIENT_PORT || localPort > MAX_CLIENT_PORT) {
212             throw new IllegalArgumentException("Invalid port number " + localPort);
213         }
214         super.connect(hostname, port, localAddr, localPort);
215     }
216 
217     // Overrides method in RExecClient in order to implement proper
218     // port number limitations.
219     @Override
220     InputStream createErrorStream() throws IOException {
221         int localPort;
222         final Socket socket;
223 
224         localPort = MAX_CLIENT_PORT;
225         ServerSocket server = null;
226 
227         for (localPort = MAX_CLIENT_PORT; localPort >= MIN_CLIENT_PORT; --localPort) {
228             try {
229                 server = _serverSocketFactory_.createServerSocket(localPort, 1, getLocalAddress());
230                 break; // got a socket
231             } catch (final SocketException e) {
232                 continue;
233             }
234         }
235 
236         if (server == null) {
237             throw new BindException("All ports in use.");
238         }
239 
240         _output_.write(Integer.toString(server.getLocalPort()).getBytes(StandardCharsets.UTF_8)); // $NON-NLS
241         _output_.write(NULL_CHAR);
242         _output_.flush();
243 
244         socket = server.accept();
245         server.close();
246 
247         if (isRemoteVerificationEnabled() && !verifyRemote(socket)) {
248             socket.close();
249             throw new IOException("Security violation: unexpected connection attempt by " + socket.getInetAddress().getHostAddress());
250         }
251 
252         return new SocketInputStream(socket, socket.getInputStream());
253     }
254 
255     /**
256      * Same as <code> rcommand(localUsername, remoteUsername, command, false); </code>
257      *
258      * @param localUsername  the local user
259      * @param remoteUsername the remote user
260      * @param command        the command
261      * @throws IOException on error
262      */
263     public void rcommand(final String localUsername, final String remoteUsername, final String command) throws IOException {
264         rcommand(localUsername, remoteUsername, command, false);
265     }
266 
267     /**
268      * Remotely executes a command through the rshd daemon on the server to which the RCommandClient is connected. After calling this method, you may interact
269      * with the remote process through its standard input, output, and error streams. You will typically be able to detect the termination of the remote process
270      * after reaching end of file on its standard output (accessible through {@link #getInputStream getInputStream() }. Disconnecting from the server or closing
271      * the process streams before reaching end of file will not necessarily terminate the remote process.
272      * <p>
273      * If a separate error stream is requested, the remote server will connect to a local socket opened by RCommandClient, providing an independent stream
274      * through which standard error will be transmitted. The local socket must originate from a secure port (512 - 1023), and rcommand() ensures that this will
275      * be so. RCommandClient will also do a simple security check when it accepts a connection for this error stream. If the connection does not originate from
276      * the remote server, an IOException will be thrown. This serves as a simple protection against possible hijacking of the error stream by an attacker
277      * monitoring the rexec() negotiation. You may disable this behavior with {@link org.apache.commons.net.bsd.RExecClient#setRemoteVerificationEnabled
278      * setRemoteVerificationEnabled()} .
279      * <p>
280      *
281      * @param localUsername       The user account on the local machine that is requesting the command execution.
282      * @param remoteUsername      The account name on the server through which to execute the command.
283      * @param command             The command, including any arguments, to execute.
284      * @param separateErrorStream True if you would like the standard error to be transmitted through a different stream than standard output. False if not.
285      * @throws IOException If the rcommand() attempt fails. The exception will contain a message indicating the nature of the failure.
286      */
287     public void rcommand(final String localUsername, final String remoteUsername, final String command, final boolean separateErrorStream) throws IOException {
288         rexec(localUsername, remoteUsername, command, separateErrorStream);
289     }
290 
291 }