Module: EtherShell::ShellDsl

Defined in:
lib/ether_shell/shell_dsl.rb

Overview

Provides the Ethernet shell DSL.

Include this in the evaluation context where you want the Ethernet shell DSL.

Defined Under Namespace

Classes: Nothing

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.nothing ⇒ Object

:nodoc: value that doesn't show up in irb



142
143
144
 
# File 'lib/ether_shell/shell_dsl.rb', line 142

def self.nothing
  @nothing ||= Nothing.new
end

.parse_mac_data(mac_data) ⇒ Object

:nodoc: turns a packet pattern into a string of raw bytes



129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/ether_shell/shell_dsl.rb', line 129

def self.parse_mac_data(mac_data)
  if mac_data.length == 12
    [mac_data].pack('H*')
  elsif mac_data.length == 14 && mac_data[0, 2] == '0x'
    [mac_data[2, 12]].pack('H*')
  elsif mac_data.kind_of? Array
    mac_data.pack('C*')
  else
    mac_data
  end
end

.parse_packet_data(packet_data) ⇒ Object

:nodoc: turns a packet pattern into a string of raw bytes



115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/ether_shell/shell_dsl.rb', line 115

def self.parse_packet_data(packet_data)
  if packet_data.kind_of? Array
    # Array of integers.
    packet_data.pack('C*')
  elsif packet_data.kind_of? String
    if packet_data[0, 2] == '0x'
      [packet_data[2..-1]].pack('H*')
    else
      packet_data
    end
  end
end

Instance Method Details

#connect(eth_device, ether_type, dest_mac) ⇒ Object

Creates a Ethernet socket for this shell.

Args:

eth_device

an Ethernet device name, e.g. 'eth0'

ether_type

2-byte Ethernet packet type number

dest_mac

MAC address of the endpoint to be tested; it can be a raw 6-byte string,



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/ether_shell/shell_dsl.rb', line 17

def connect(eth_device, ether_type, dest_mac)
  raise "Already connected. did you forget to call disconnect?" if @_socket
  mac_bytes = EtherShell::ShellDsl.parse_mac_data dest_mac
  @_socket = Ethernet.socket eth_device, ether_type
  @_socket.connect mac_bytes
  if @_verbose
    print ['Connected to ', mac_bytes.unpack('H*').first, ' using ',
           '%04x' % ether_type, ' via ', eth_device, "\n"].join
  end
  @_nothing = ''
  class <<@_nothing
    def inspect
      ''
    end
  end
  EtherShell::ShellDsl.nothing
end

#disconnect ⇒ Object

Disconnects this shell's Ethernet socket.

A socket should have been connected previously, using connect or socket. The shell can take further connect and socket calls.



39
40
41
42
43
44
45
 
# File 'lib/ether_shell/shell_dsl.rb', line 39

def disconnect
  raise "Not connected. did you forget to call connect?" unless @_socket
  @_socket.close
  @_socket = nil
  print "Disconnected\n" if @_verbose
  EtherShell::ShellDsl.nothing
end

#expect(packet_data) ⇒ Object

Receives a packet and matches it against an expected value.

Args:

packet_data

an Array of integers (bytes), a hex string starting with 0x, or a string of raw bytes

Raises:

RuntimeError

if the shell was not connected to a socket by a call to connect or socket

RuntimeError

if the received packet doesn't match the expected value



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/ether_shell/shell_dsl.rb', line 97

def expect(packet_data)
  raise "Not connected. did you forget to call connect?" unless @_socket
  expected_bytes = EtherShell::ShellDsl.parse_packet_data packet_data
  
  print "Receiving... " if @_verbose
  bytes = @_socket.recv
  print " #{bytes.unpack('H*').first} " if @_verbose
  if bytes == expected_bytes
    print "OK\n" if @_verbose
  else
    print "!= #{expected_bytes.unpack('H*').first} ERROR\n" if @_verbose
    raise EtherShell::ExpectationError,
        "#{bytes.unpack('H*').first} != #{expected_bytes.unpack('H*').first}"
  end
  EtherShell::ShellDsl.nothing
end

#out(packet_data) ⇒ Object

Outputs a packet.

Args:

packet_data

an Array of integers (bytes), a hex string starting with 0x, or a string of raw bytes

Raises:

RuntimeError

if the shell was not connected to a socket by a call to connect or socket



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/ether_shell/shell_dsl.rb', line 76

def out(packet_data)
  raise "Not connected. did you forget to call connect?" unless @_socket
  bytes = EtherShell::ShellDsl.parse_packet_data packet_data
  
  
  print "Sending #{bytes.unpack('H*').first}... " if @_verbose
  @_socket.send bytes
  print "OK\n" if @_verbose
  EtherShell::ShellDsl.nothing
end

#socket(high_socket) ⇒ Object

Connects this shell to a pre-created socket

Args:

high_socket

socket that behaves like an EtherShell::HighSocket



51
52
53
54
55
56
 
# File 'lib/ether_shell/shell_dsl.rb', line 51

def socket(high_socket)
  raise "Already connected. did you forget to call disconnect?" if @_socket
  @_socket = high_socket
  print "Connected directly to socket\n" if @_verbose
  EtherShell::ShellDsl.nothing
end

#verbose(true_or_false = true) ⇒ Object

Enables or disables the console output in out and expect.

Args:

true_or_false

if true, out and expect will produce console output



62
63
64
65
 
# File 'lib/ether_shell/shell_dsl.rb', line 62

def verbose(true_or_false = true)
  @_verbose = true_or_false
  EtherShell::ShellDsl.nothing
end