Class: Cisco::Client::NXAPI

Inherits:
Cisco::Client show all
Defined in:
lib/cisco_node_utils/client/nxapi.rb,
lib/cisco_node_utils/client/nxapi/client.rb

Overview

Class representing an HTTP client connecting to a NXAPI server.

Constant Summary collapse

NXAPI_UDS =

Location of unix domain socket for NXAPI localhost

'/tmp/nginx_local/nginx_1_be_nxapi.sock'
NXAPI_REMOTE_URI_PATH =

NXAPI listens for remote connections to “http://<switch IP>/ins” NXAPI listens for local connections to “http://<UDS>/ins_local”

'/ins'
NXAPI_UDS_URI_PATH = 
'/ins_local'
NXAPI_VERSION =

Latest supported version is 1.0

'1.0'

Instance Attribute Summary

Attributes inherited from Cisco::Client

#cache_auto, #data_formats, #platform

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Cisco::Client

#cache_auto?, #cache_enable=, #cache_enable?, clients, create, filter_cli, filter_data, find_subconfig, handle_errors, #inspect, #munge_to_array, munge_to_array, register_client, silence_warnings, #supports?, to_regexp, #to_s

Constructor Details

#initialize(**kwargs) ⇒ NXAPI

Constructor for Client. By default this connects to the local unix domain socket. If you need to connect to a remote device, you must provide the host/username/password parameters.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 41

def initialize(**kwargs)
  # rubocop:disable Style/HashSyntax
  super(data_formats: [:nxapi_structured, :cli],
        platform:     :nexus,
        **kwargs)
  # rubocop:enable Style/HashSyntax
  # Default: connect to unix domain socket on localhost, if available
  if @host.nil?
    unless File.socket?(NXAPI_UDS)
      fail Cisco::ConnectionRefused, \
           "No host specified but no UDS found at #{NXAPI_UDS} either"
    end
    # net_http_unix provides NetX::HTTPUnix, a small subclass of Net::HTTP
    # which supports connection to local unix domain sockets. We need this
    # in order to run natively under NX-OS but it's not needed for off-box
    # unit testing where the base Net::HTTP will meet our needs.
    require 'net_http_unix'
    @http = NetX::HTTPUnix.new('unix://' + NXAPI_UDS)
    @cookie = kwargs[:cookie]
  else
    # Remote connection. This is primarily expected
    # when running e.g. from a Unix server as part of Minitest.
    @http = Net::HTTP.new(@host)
  end
  # The default read time out is 60 seconds, which may be too short for
  # scaled configuration to apply. Change it to 300 seconds, which is
  # also used as the default config by firefox.
  @http.read_timeout = 300
  @address = @http.address
end

Class Method Details

.validate_args(**kwargs) ⇒ Object 



72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 72

def self.validate_args(**kwargs)
  super
  if kwargs[:host].nil?
    # Connection to UDS - no username or password either
    fail ArgumentError unless kwargs[:username].nil? && kwargs[:password].nil?
    validate_cookie(**kwargs)
  else
    # Connection to remote system - username and password are required
    fail TypeError, 'username is required' if kwargs[:username].nil?
    fail TypeError, 'password is required' if kwargs[:password].nil?
  end
end

.validate_cookie(**kwargs) ⇒ Object 



85
86
87
88
89
90
91
92
93
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 85

def self.validate_cookie(**kwargs)
  return if kwargs[:cookie].nil?
  format = 'Cookie format must match: <username>:local'
  msg = "Invalid cookie: [#{kwargs[:cookie]}]. : #{format}"

  fail TypeError, msg unless kwargs[:cookie].is_a?(String)
  fail TypeError, msg unless /\S+:local/.match(kwargs[:cookie])
  fail ArgumentError, 'empty cookie' if kwargs[:cookie].empty?
end

Instance Method Details

#cache_flush ⇒ Object

Clear the cache of CLI output results.

If cache_auto is true (default) then this will be performed automatically whenever a set() is called, but providers may also call this to explicitly force the cache to be cleared.



100
101
102
103
104
105
106
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 100

def cache_flush
  @cache_hash = {
    'cli_conf'       => {},
    'cli_show'       => {},
    'cli_show_ascii' => {},
  }
end

#get(data_format: :cli, command: nil, context: nil, value: nil, **_kwargs) ⇒ String, Hash

Get the given state from the device.

Unlike set() this will not clear the CLI cache; multiple calls with the same parameters may return cached data rather than querying the device repeatedly.

Parameters:

  • data_format (defaults to: :cli) —

    one of Cisco::DATA_FORMATS. Default is :cli

  • command (String) (defaults to: nil) —

    the show command to execute

  • context (String, Array<String>) (defaults to: nil) —

    Context to refine the results

  • value (String) (defaults to: nil) —

    Specific key to look up

  • kwargs —

    data-format-specific args

Returns:

  • (String, Hash)

Raises:



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 146

def get(data_format: :cli,
        command:     nil,
        context:     nil,
        value:       nil,
        **_kwargs)
  context = munge_to_array(context)
  super
  if data_format == :cli
    output = req('cli_show_ascii', command)
    return self.class.filter_cli(cli_output: output,
                                 context:    context,
                                 value:      value)
  elsif data_format == :nxapi_structured
    output = req('cli_show', command)
    return self.class.filter_data(data: output,
                                  keys: context + munge_to_array(value))
  else
    fail TypeError
  end
end

#read_timeout_check(request) ⇒ Object

Helper method to increase the default @http.read_timeout value from the default value of 300 to accomodate commands that are known to require more time to complete.



170
171
172
173
174
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 170

def read_timeout_check(request)
  return unless request.body[/install all|install force-all/]
  debug("Increasing http read_timeout to 1000 for 'install all' command")
  @http.read_timeout = 1000
end

#set(data_format: :cli, context: nil, values: nil, **_kwargs) ⇒ Object

Configure the given CLI command(s) on the device.

Parameters:

  • data_format (defaults to: :cli) —

    one of Cisco::DATA_FORMATS. Default is :cli

  • context (String, Array<String>) (defaults to: nil) —

    Zero or more configuration commands used to enter the desired CLI sub-mode

  • values (String, Array<String>) (defaults to: nil) —

    One or more commands to enter within the CLI sub-mode.

  • kwargs —

    data-format-specific args

Raises:



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/cisco_node_utils/client/nxapi/client.rb', line 118

def set(data_format: :cli,
        context: nil,
        values: nil,
        **_kwargs)
  # we don't currently support nxapi_structured for configuration
  fail Cisco::RequestNotSupported if data_format == :nxapi_structured
  context = munge_to_array(context)
  values = munge_to_array(values)
  super
  req('cli_conf', context + values)
end