j2ssh-getting-started.htm

j2ssh document for java dev

  to<br>
  be prompted for the information once the authenticate method has been invoked.</font></p>
<blockquote>
  <pre>
public interface SshAuthenticationPrompt {
  public boolean showPrompt(SshAuthenticationClient instance) 
                              throws AuthenticationProtocolException;
  }
}</pre>
</blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> The showPrompt 
  method is called if the authentication instance is not ready to authenticate. 
  The methods is called and the developer should verify the instance of the SshAuthenticationClient 
  to make sure that it is compatible with the prompt (for example you cannot perform 
  public key authentication<br>
  with a password prompt!). The user should then be duly prompted for the information 
  and the instance set with the user's information. Once<br>
  complete, the prompt returns true to indicate that the user successfully entered 
  correct information.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> There are several 
  prompts provided in the J2SSH common packages that provide useful Swing based 
  dialogs to<br>
  prompt the user.</font></p>
<blockquote>
  <pre> 
import com.sshtools.common.authentication.PasswordAuthenticationDialog;
  
/***
* Create a PasswordAuthenticationDialog instance and call the
* showAuthenticationMethod so the user can graphically
* enter their username and password
*/


PasswordAuthenticationClient pwd = 
            new PasswordAuthenticationClient();
			
PasswordAuthenticationDialog dialog = 
            new PasswordAuthenticationDialog(parent);
			
pwd.setAuthenticationPrompt(dialog);

int result;
result = ssh.authenticate(pwd);
  </pre>
</blockquote>
<!--pagebreak-->
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><strong><em>Using 
  a session channel to execute a command or start the users shell</em></strong></font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> Once the user 
  is authenticated you will probably want to do something such as execute a command 
  or start the users shell. The SSH protocol provides multiplexed channels over 
  a single connection and the session channel is one of the channels defined by 
  the SSH protocol. The session channel allows the client to execute a single 
  command on the remote host and to communicate with the process by sending and 
  receiving data. The J2SSH SessionChannelClient implements this channel and we 
  will use this to execute a basic "ls" command.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">The session channel provides 
  an inputstream and outputstream for reading/writing, but before we can do this 
  we need to setup the channel for our command. First we open the channel itself 
  by calling the SshClient method:</font></p>
<blockquote>
  <pre> 
SessionChannelClient session = ssh.openSessionChannel();</pre>
</blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> Now that we have 
  a session instance we need to configure it for our command, there are several 
  options that can be set before we invoke one of the methods that will start 
  the session.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><em>Setting Environment 
  Variables<br>
  </em>The SSH protocol provides a method to set an environment variable for the 
  processes environment, the protocol also leaves the actual implementation of 
  this down the server implementation, and in our experience most servers do not 
  allow for this for security reasons. However the method is available since its 
  defined in the protocol specification, so your free to try to use it, but beware 
  the variable may not be set!</font></p>
<blockquote><code> public boolean 
  setEnvironmentVariable(String name, String value);</code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><em>Requesting 
  a Pseudo Terminal</em><br>
  A pseudo terminal is a device that imitates a terminal. Rather than being connected 
  to an actual terminal, a pseudo-terminal (or pty) is connected to a process. 
  If the command you are executing is expecting a terminal (such as a shell command) 
  you can request that a pseudo terminal be attached to the process by calling 
  the requestPseudoTerminal method.</font></p>
<blockquote><code> public boolean 
  requestPseudoTerminal(String term, int cols, int rows, int width, int height, 
  String modes);</code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><em>Invoking a 
  command<br>
  </em>After the above operations have been performed you can then request that 
  the session either start the user's shell, execute a specific command or start 
  an SSH subsystem (such as SFTP). You should not invoke a subsystem unless you 
  are able to read/write the subsystem protocol, there are many additional utilities 
  within J2SSH that provide for the available subsystems.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">To start the users 
  default shell use:</font></p>
  <blockquote>
  <code>public boolean startShell();</code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Or to execute a 
  specific command use:</font></p>
<blockquote><code>public boolean 
  executeCommand(String command);</code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><em>An important 
  note to remember is that this does not execute a shell command. You cannot for 
  instance issue the command executeCommand("dir")" on the Windows 
  Operating system as this is a shell command, instead use "cmd.exe /C dir". 
  This method executes a binary executable and so should be used to execute any 
  program other than the users shell.</em></font></p>
  <!--pagebreak-->
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> <strong><em>Handling 
  Session Data</em></strong><br>
  Once the session has been configured and a command or shell has been started, 
  you can begin to<br>
  transfer data to and from the remote computer using the sessions IO streams. 
  These streams provide you with a<br>
  standardized interface for reading and writing the data.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><em> The Session 
  Channel's OutputStream</em><br>
  The format of writing data varies according to how you configured the session, 
  for example if you executed the<br>
  users shell then the data should be written as if the user had entered the commands 
  interactively.</font></p>
<blockquote><pre> 
/** Writing to the session OutputStream */
OutputStream out = session.getOutputStream();
String cmd = "ls\n";
out.write(cmd.getBytes());</pre></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> <em> The Session 
  Channel's InputStream</em></font></p>
<blockquote><pre>
/**
* Reading from the session InputStream
*/
InputStream in = session.getInputStream();
byte buffer[] = new byte[255];
int read;
while((read = in.read(buffer)) > 0) {
   String out = new String(buffer, 0, read);
   System.out.println(out);
}
</pre></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> <em>Reading from 
  stderr</em><br>
  The session also provides the stderr data provided by the remote session. Again 
  an InputStream is provided.</font></p>
<blockquote><code> public InputStream 
  session.getStderrInputStream();<br>
  </code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><strong><em>Closing 
  the Session</em></strong></font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">The session can 
  be closed using the following method:</font></p>
<blockquote><code> public void close();</code></blockquote>
<p><em><strong><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Disconnecting</font></strong></em></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> The connection 
  can be terminated by either side. To terminate the connection call the SshClient 
  method:</font></p>
  <blockquote><code>
  public void disconnect();</code></blockquote>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"> <em><strong>A 
  word on executing multiple commands</strong></em></font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">So we can now execute 
  a single command on the remote server, but what's that I hear you say? I want 
  to execute more than one command? Well if you cast your mind back I told you 
  that the SSH protocol provides multiplexed channels over a single connection, 
  so executing another command is as simple as executing the first, just create 
  a new instance of the SessionChannelClient for every command you want to execute. 
  You can execute them simultaneously or one after another, but always create 
  a new session (since the session is closed when the command finishes and the 
  protocol does not allow for re-using of a session to execute another command). 
  </font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">There is a drawback 
  to this in that the process environment is not passed on from one session to 
  another, so you cannot for example execute a command to change directory and 
  then another to execute a script in that directory, since the change directory 
  is lost when the session closes and the new command starts back in the default 
  working directory. Of course you could always put the cd command into the script? 
  Or use the shell to execute both commands. This subject is certainly a bit more 
  advanced so I will leave it for another day and pencil in a new article to discuss 
  all the alternatives for executing multiple commands. </font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">This concludes 
  our getting started tutorial, you should now have a basic working knowledge 
  of how to connect, authenticate and execute commands using J2SSH. </font></p>
</body>
</html>