net-ops 0.0.5.pre → 0.0.6.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ddd5aa75208c9e4c9cca7e3b132134453117747
-  data.tar.gz: 7f7cb228b4234a18e901c3d0bf77d19a0c637c90
+  metadata.gz: 34f9d13e55ceb5c908ac02977a65af34cf800351
+  data.tar.gz: 590c49b48e2f3332638b6fbc15957db6986345c8
 SHA512:
-  metadata.gz: 024cbbd43efc3e9381db9fa65446fee4f08626cb424cebeefefe04ec039f9679f23cd85d9d6fcbde32f95cc956af0f0212b5f1a089164ecb107c47f106ff8ad0
-  data.tar.gz: b74d3628a96ae7753f37268c5031be99251ee92321b3985255bdb2a209274211fd189e9ec4a0b9cd1088cd73aab24c52e105829af685321de3434d1ac5afcfb8
+  metadata.gz: c0a759af3c60da04e28c79483b2f373b53747b535c12165202a65fa08291cef52a6020f8f492fdbd57ee0ae52557ac92e4eb8df348867a9fbdd6da3532c8b687
+  data.tar.gz: 3aed13236fa58b023460b17c326cf4314c8d9ddc868a39349b38137231734de471821c4b02d756fb21b2ed9c0841c95d149cec01ff119d90573e0673272b8f17

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+Gemfile.lock
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+credentials.yml
+*~

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in net-ops.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Maxime Mouchet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,334 @@
+# Net::Ops
+
+## Ruby framework for interacting with network devices
+
+Computers are made to simplify our lives, not make them more complicated. They don't mind doing 1000x the same thing but too often people do repetitive tasks at hand because they don't know how to write scripts.
+I developed this little Ruby module to simplify daily operations on network devices like switches, routers, and access-points.
+
+### Prerequisites
+
+I made it to be as simple as possible but, if you want to understand how it works or extend it, you will need some Ruby knowledge.
+[The Little Book of Ruby](http://www.sapphiresteel.com/The-Little-Book-Of-Ruby) is a good introduction altough convention are not always clear.
+[Design Patterns](http://www.amazon.fr/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612) and [Design Patterns in Ruby](http://www.pearsonhighered.com/educator/product/Design-Patterns-in-Ruby/9780321490452.page)
+are must read.
+[Stack Overflow](http://stackoverflow.com/) is a good place in case of problem.
+
+### Compatibility
+
+Tested with Cisco IOS and IOS XE devices. Should work partially with NX-OS.
+Not compatible with IOS XR and non-Cisco devices but it would be possible to add an abstraction layer in ops.rb to support other brands.
+
+I implemented only two [transports](#transports), Telnet and SSH. If you want to use another protocol (a serial link for example) you will have to implement it.
+
+
+## Installation
+
+First, you need a Ruby interpreter. [MRI](http://en.wikipedia.org/wiki/Ruby_MRI), the reference implementation, is a good choice. You can download it on [ruby-lang.org](http://www.ruby-lang.org/en/downloads/).
+Note that MRI is already included in Mac OS X and most of the Linux distributions.
+On Ubuntu you can install it with `apt-get install ruby1.9.3`.
+There is other Ruby implementation like [JRuby](http://jruby.org/) or [MagLev](http://maglev.github.io/) but I have not tested my code with them.
+
+Then you should intall net-ops. You can get the latest version from RubyGems:
+```bash
+gem install 'net-ops'
+```
+
+Or build it from the source:
+```bash
+gem build net-ops.gemspec
+gem install ./net-ops-x.y.z.gem
+```
+
+## Getting started
+
+You need to require net/ops in all your scripts and [tasks](#tasks) (we will talk about this later):
+
+```ruby
+require 'net/ops'
+```
+
+To run a script you can double-click on it (on Windows) or issue `ruby my_script.rb` in a terminal.
+
+### Storing credentials
+
+Writing directly your username and password directly in the script is a bad idea.
+If you want to keep things simple you can store them in a [YAML](http://en.wikipedia.org/wiki/YAML) file with the following structure:
+```yml
+# credentials.yml
+username: user1
+password: r5Xqx8
+```
+Then, to use them in your script:
+
+```ruby
+credentials = YAML.load_file('credentials.yml')
+
+credentials.fetch('username') #=> 'user1'
+credentials.fetch('password') #=> 'r5Xqx8'
+```
+
+*Note 1 : If you don't need a username to connect to your device you can either let it empty or specify any value. The field will be ignored.*
+*Note 2 : Currently the login and the enable password used are the same ([issue #4](https://github.com/maxmouchet/net-ops/issues/4))*
+
+### Connecting to a device
+
+Connecting to a device is a two-step process: create a session, and open it.
+Nothing is sent on the transport until you open the session.
+
+#### Create the session
+
+To create a Session you just need to specify the hostname (or the IP address):
+
+```ruby
+@session = Net::Ops::Session.new('router1.local')
+```
+
+##### Options
+
+You can also customize the timeout (`Integer`) and the prompt (`Regexp`) if you want:
+
+```ruby
+host    = 'router1.local'
+options = { timeout: 10, prompt: /.+(#|>)/ }
+
+@session = Net::Ops::Session.new(host, options)
+```
+
+##### Logging
+
+By default `Session` logs everything from `Level::DEBUG` to `STDOUT`. You can specify a custom logger to the constructor.
+For example to log everything from `Level::WARN` to a file:
+```ruby
+logger = Logger.new('logfile.log')
+logger.level = Logger::WARN
+
+@session = Net::Ops::Session.new(host, options, logger)
+```
+
+#### Open the session
+
+Given you loaded your credentials from a YAML file you can open the session like this:
+
+```ruby
+@session.open({ username: credentials.fetch('username'),
+               password: credentials.fetch('password') })
+```
+
+Note that this doesn't handle `Net::Ops::TransportUnavailable` which is raised when no transport can be used to open the session.
+To show the error and prevent your script from stopping:
+
+```ruby
+begin @session.open({ username: '', password: '' })
+rescue Net::Ops::TransportUnavailable => e
+  puts "There is an error: #{e.message}"
+end
+```
+
+#### Close the session
+
+It is generally not needed to close the session since the Ruby garbage collector will do it automatically.
+However if you need to, you can call `close`:
+```ruby
+@session.close
+```
+
+### Sending commands
+
+Once the session is opened you can send commands to the device. Net::Ops offer three abstraction levels that are described below.
+
+#### Raw commands
+
+The basic way to send a command and get the output is the `run(command)` method.
+It send command (`String`) followed by a carriage return to the device, wait for the prompt, and return what happened between.
+For example, to get `show int status` output:
+
+```ruby
+puts @session.run('show int status')
+```
+
+`run(command)` is pretty low-level but sometimes you will want to play directly with the transport.
+For example when the command ask for confirmation and doesn't return the prompt (like `reload`). In this case you can do something like this:
+```ruby
+transport = @session.transport
+transport.cmd('String' => 'reload', 'Match' => /.+confirm.+/)
+transport.cmd('yes')
+```
+
+To get the output with `transport.cmd` you need to pass a block:
+
+```ruby
+transport = @session.transport
+transport.cmd('show version') { |c| puts c }
+```
+
+
+#### Basic commands
+
+To make your script easier to read, Net::Ops provides methods which are basically alias to Cisco commands.
+These are `get(item)`, `set(item, value)`, `enable(item)`, and `disable(item)`:
+```ruby
+@session.get 'interfaces status'
+# send 'show interfaces status'
+
+@session.set 'terminal length', 0
+# send 'terminal length 0'
+
+@session.enable 'ip http secure-server'
+# send 'ip http secure-server'
+
+@session.disable 'spanning-tree bpduguard'
+# send 'no spanning-tree bpduguard'
+```
+
+These methods allow you to write script that are easily readable but you can do much more by combining them with the [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) that Net::Ops provides.
+
+#### Domain-specific language
+
+Currently the DSL is made of five methods:
+* `privileged(&block)`
+* `configuration(options = nil, &block)`
+* `interface(interface, &block)`
+* `interfaces(interfaces, &block)`
+* `lines(lines, &block)`
+
+They allow you to run commands in the specified context. Note that don't have to prefix methods with `@session` since the block is evalued inside the session.
+
+Here's an example of how to use it:
+```ruby
+# Here we pass a block to be executed in the privileged mode.
+@session.privileged do
+
+  # Let's get interfaces status.
+  sw_interfaces = get 'interfaces status'
+
+  # Show disabled interfaces
+  nc_interfaces = sw_interfaces.select { |int| int['status'] == 'disabled' }
+  puts nc_interfaces
+
+end
+
+# Do some stuff in configuration mode.
+@session.configuration do
+
+  # Add description to Gi1/0/2.
+  # Note the singular/plural in interface(s).
+  # interface accept only String as an argument.
+  # interfaces accept Array, Regexp, and String.
+  interface('Gi1/0/2') do
+    set 'description', 'I am Gi1/0/2'
+  end
+
+  # Disable bpduguard on all Gig interfaces.
+  interfaces(/Gi1\/0/) do
+    disable 'spanning-tree bpduguard'
+  end
+
+end
+
+# Copy to startup-config
+@session.write!
+
+# Do something else in configuration mode
+# but automatically write this time.
+@session.configuration(:enforce_save) do
+  disable 'ip http secure-server'
+end
+```
+
+#### Other commands
+
+* `write!`
+* `zeroize(item)`
+* `generate(item, options)`
+
+Example :
+
+```ruby
+# Delete the crypto key
+@session.zeroize 'crypto key'
+
+# Regenerate it
+@session.generate 'crypto key', 'rsa general-keys modulus 2048'
+
+# Save running-config
+@session.write!
+```
+
+## Tasks
+Net::Ops allow to define tasks that perform a specific action and run it on several devices in parallel while handling errors and providing easy logging.
+
+### Definition
+To define a task you should create a new class that inherit from `Task` and define `initialize` and `work` methods:
+
+```ruby
+# my_task.rb
+class MyTask < Net::Ops::Task
+
+  def initialize(id)
+    # Setup your stuff.
+    super(id)
+  end
+
+  def work
+    # Place your logic here.
+  end
+
+end
+```
+
+`id` is an identifier that should be unique for each instance of your task. You can use whatever you want, for example the hostname of the device you are currently working on.
+
+### Execution
+To run a task you can basically instance it and call work:
+
+```ruby
+t = MyTask.new('task1')
+t.work
+```
+
+However you may want to run several tasks in parallel to speed up things. You can do that thanks to [thread/pool](https://github.com/meh/ruby-thread):
+
+```ruby
+hosts = %w( host1 host2 host3 )
+max_conn = 2
+
+pool = Thread.pool(max_conn)
+
+hosts.each do |hosts|
+  pool.process { MyTask.new(host).work }
+end
+
+pool.shutdown
+```
+
+## Transports
+
+### Built-in
+
+### Custom
+```ruby
+class MyCustomTransport
+
+  def self.open(host, options, credentials)
+    session = # Do what you need to get a session to the host.
+    return session
+  end
+
+end
+```
+
+## Documentation
+You can get the documentation via gem with `gem server`.
+Or generate it manually with `rake doc`.
+
+## Todo - Ideas
+
+See [issues](https://github.com/maxmouchet/net-ops/issues?state=open).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/examples/basic_script.rb

@@ -0,0 +1,94 @@
+# Sample script that show basic usage of Net::Ops.
+# For more information refer to the documentation.
+# To generate it run `yardoc lib/net/ops/session.rb`.
+
+# Add lib/ to the PATH.
+$:.unshift File.join(File.dirname(__FILE__), *%w[lib])
+
+require 'rubygems'
+require 'net/ops'
+require 'yaml'
+
+# Load credentials from credentials.yml.
+#
+# File format is :
+# username: myusername
+# password: mypassword
+credentials = YAML.load_file('credentials.yml')
+
+# Define the timeout and the prompt (optional).
+# Net::Ops::Session.new default to
+# { timeout: 10, prompt: /.+(#|>)/ }
+options = { timeout: 10, prompt: /.+(#|>)/ }
+
+# Create a logger (optional).
+# Net::Ops::Session.setup_logger default to
+# logger = Logger.new(STDOUT)
+# logger.level = Logger::DEBUG
+logger = Logger.new(STDOUT)
+logger.level = Logger::DEBUG
+
+# Create a session to sa-qcmtlv-11-09 (1).
+# This is the exhaustive form with all optionals params.
+session = Net::Ops::Session.new('sa-qcmtlv-11-09', options, logger)
+
+# OR
+
+# Create a session to sa-qcmtlv-11-09 (2).
+# This is the short form without the optional params.
+# See the documentation/code for default values.
+session = Net::Ops::Session.new('sa-qcmtlv-11-09')
+
+# Open the session using the specified credentials.
+# This form provides the full hash in case
+# key names are not :username and :password.
+# Or if you want to specify credentials directly.
+session.open({ username: credentials.fetch('username'),
+               password: credentials.fetch('password') })
+
+# Set terminal length to 0 otherwise too long outputs will cause
+# Net::Telnet to timeout while waiting for the prompt.
+session.privileged { set 'terminal length', 0 }
+
+# Here we pass a block to be executed in the privileged mode.
+session.privileged do
+
+  # Let's get interfaces status.
+  sw_interfaces = get 'interfaces status'
+  
+  # Show disabled interfaces
+  @nc_interfaces = sw_interfaces.select { |int| int['status'] == 'disabled' }
+  puts @nc_interfaces
+  
+end
+
+# Do some stuff in configuration mode.
+session.configuration do
+
+  # Add description to Gi1/0/2.
+  # Note the singular/plural in interface(s).
+  # interface accept only String as an argument.
+  # interfaces accept Array, Regexp, and String.
+  interface('Gi1/0/2') do
+    set 'description', 'I am Gi1/0/2'
+  end
+  
+  # Disable bpduguard on all Gig interfaces.
+  interfaces(/Gi1\/0/) do
+    disable 'spanning-tree bpduguard'
+  end
+  
+end
+
+# Copy to startup-config
+session.write!
+
+# Do something else in configuration mode
+# but automatically write this time.
+session.configuration(:enforce_save) do
+  disable 'ip http secure-server'
+end
+
+# Close the session.
+# Optionnal since Ruby garbage collector should do that for us.
+session.close