5. User Shells
5.1. Introduction
A user’s shell is the environment in which commands are executed on a remote machine. There are a variety of different shells, including bash, csh, tcsh, ksh, and many others.
A shell may be executed like any other program, and when run, it (more-or-less) enters a read-execute-prompt cycle in which the user may interactively run commands.
SSH has special support for shells, allowing you to start a shell on a channel and have all subsequent data sent to that channel interpreted as the user’s input to the shell. Also, SSH supports pty’s (pseudo-tty’s, or terminals), which allow the shell to act as if it were running locally on the users own machine.
Because a shell is just a program, you can always start a shell simply by executing it (as described in the previous chapter). However, you can also take advantage of SSH’s builtin shell support to execute the user’s preferred shell. This chapter will discuss this approach.
5.2. Using Channels
At the lowest level, starting a shell is a matter of sending a “shell” request over a channel.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | Net::SSH.start( host ) do |session| session.open_channel do |channel| channel.on_success do puts "shell was started successfully!" channel.send_data "exit\n" # tell the shell to exit end channel.on_failure do puts "shell could not be started!" end channel.on_data do |ch,data| puts "recieved #{data} from shell" end channel.on_close do puts "shell terminated" end channel.send_request "shell", nil, true end session.loop end |
The #send_request
method accepts three parameters—the name of the request (in this case, “shell”), any additional data to send with the request (none, in this case), and whether or not you want the server to reply with the success or failure of the request. In general, it is a good idea to ask for the server to reply, so that you know when you can start sending data to the shell.
If you want to open a pty before starting the shell, you can use the #request_pty method of the channel:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | Net::SSH.start( host ) do |session| session.open_channel do |channel| channel.on_success do puts "pty was requested successfully!" channel.on_success do puts "shell was started successfully!" channel.send_data "exit\n" # tell the shell to exit end channel.send_request "shell", nil, true end channel.on_failure do puts "shell could not be started!" end channel.on_data do |ch,data| puts "recieved #{data} from shell" end channel.on_close do puts "shell terminated" end channel.request_pty :want_reply => true end session.loop end |
First, the pty is requested (with an indicator to the server that it should return a “success” or “failure” notification). When the pty is successfully opened, the “on_success” callback is changed, and the shell is then requested.
It’s a lot of hoops to jump through, but it gives you the finest-grained control over opening a shell. For most things, though, you can live with less control. For those tasks, there are the shell and sync services.
5.3. Shell Service
To make interacting with shells, simpler, version 0.9 of Net::SSH introduced the shell service. This allows you to open a shell (with or without a pty), send a series of commands to the shell, and then wait for the output from the shell.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | Net::SSH.start( 'localhost' ) do |session| shell = session.shell.open # script what we want to do shell.pwd shell.cd "/" shell.pwd shell.test "-e foo" shell.cd "/really/bogus/directory" shell.send_data "/sbin/ifconfig\n" shell.pwd shell.ruby "-v" shell.cd "/usr/lib" shell.pwd shell.exit # give the above commands sufficient time to terminate sleep 0.5 # display the output $stdout.print shell.stdout while shell.stdout? $stderr.puts "-- stderr: --" $stderr.print shell.stderr while shell.stderr? end |
Any unrecognized method that is sent to the shell object is interpreted as a command to send to the server. To explicitly send a command, use the #send_data
method (but remember to add a newline!). The #send_data
method may also be used to send data to any process running in the shell as that process’ stdin
stream.
You can also specify that a pty should be allocated for this shell:
1 2 3 4 5 6 7 8 9 | Net::SSH.start( 'localhost' ) do |session| shell = session.shell.open( :pty => true ) # or shell = session.shell.open( :pty => { ... } ) end |
If you give a hash for the :pty
option, it must be a map of the options that describe the new pty. See the API documentation for the Channel#request_pty
method for more information.
Note that this is still an asynchronous approach. You send all the commands through the pipe and then wait for the output. (And be sure to give sufficient time or the processes to terminate!) This is fine for scripts that you just want to throw at the server, but many times you want a more interactive interface, for executing a command and receiving its output before moving on.
5.4. SyncShell Service
The SyncShell service allows you to execute commands on the shell and block until they finish. It is not fool-proof—it has to use some tricks to accomplish this task, and some commands may foul it up. But for most tasks, it works admirably.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | Net::SSH.start( 'localhost' ) do |session| shell = session.shell.sync out = shell.pwd p out.stdout out = shell.test "-e foo" p out.status out = shell.cd "/really/bogus/directory" p out.stderr p out.status out = shell.ruby "-v" p out.stdout out = shell.cd "/usr/lib" out = shell.ls "-l" p out.stdout out = shell.send_command( "bc", <<CMD ) 5+5 10*2 scale=5 3/4 quit CMD p out.stdout p shell.exit end |
The result of executing each command is an object that encapsulates the stdout
and stderr
streams, and the exit status of the command.
To explicitly execute a command, use the #send_command
instead of #send_data
—otherwise, the command will be executed asynchronously, which is not what you want. Also, if you pass a second parameter to the #send_command
method, it is interpreted as the stdin
data to send to the new process.
5.5. Terminal Clients
Using the shell service and pty’s, you can now create a simple SSH terminal client. (You’ll also want to download and install the ruby-termios library so that your input is not interpreted in a linewise fashion.)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | begin require 'termios' rescue LoadError end def stdin_buffer( enable ) return unless defined?( Termios ) attr = Termios::getattr( $stdin ) if enable attr.c_lflag |= Termios::ICANON | Termios::ECHO else attr.c_lflag &= ~(Termios::ICANON|Termios::ECHO) end Termios::setattr( $stdin, Termios::TCSANOW, attr ) end host = ARGV.shift or abort "You must specify the [user@]host to connect to" if host =~ /@/ user, host = host.match( /(.*?)@(.*)/ )[1,2] else user = ENV['USER'] || ENV['USER_NAME'] end Net::SSH.start( host, user ) do |session| begin stdin_buffer false shell = session.shell.open( :pty => true ) loop do break unless shell.open? if IO.select([$stdin],nil,nil,0.01) data = $stdin.sysread(1) shell.send_data data end $stdout.print shell.stdout while shell.stdout? $stdout.flush end ensure stdin_buffer true end end |
The above code is also available as an example script in the Net::SSH distribution (examples/ssh-client.rb
).