junos-ez-stdlib 0.0.12 → 0.0.15

data/CHANGELOG.md

@@ -1,19 +1,33 @@
 # 2013-April
 
-  0.0.10: 2013-04-29
+  0.0.10: 2013-04-26
   
     Initial release of code into RubyGems.  Code tested on EX and SRX-branch. Consider this code
     as "early-adopter".  Comments/feedback is welcome and appreciated.
 
-  0.0.11: 2013-04-29
+  0.0.11: 2013-04-26
   
     Updated Junos::Ez::RE::Utils
       #memory changed :procs from Hash to Array  
       #users changed return from Hash to Array
     
-  0.0.12: 2013-04-29 (In-Progress)
+  0.0.12: 2013-04-26
   
     Updated Junos::Ez::FS:Utils#ls to include :symlink information
     Adding Junos::Ez::Users::Provider for login management
     Adding Junos::Ez::UserAuths::Provider for SSH-key management
     
+  0.0.14: 2013-04-28
+  
+    Completed initial documentation.  Still more work to be done with these files
+    but the "enough to get started" information is now available
+
+  0.0.15: 2013-05-02
+  
+    L2ports - added support for framework to read [edit vlans] stanza to recognize interfaces configured
+    there vs. under [edit interfaces]
+    
+    IPports - added :acl_in and :acl_out for stateless ACL filtering.  added .status method to return
+    runtime status information about the port
+    
+    RE::Utils - misc updates, and documentation

data/README.md

@@ -179,3 +179,13 @@ documentation on Providers/Resources, see the *docs* directory.
 # LICENSES
 
    BSD-2, See LICENSE file
+
+# SUPPORT
+
+Support for this software is made available exclusively through Github repo issue tracking.  You are also welcome to contact the CONTRIBUTORS directly via their provided contact information.  
+
+If you find a bug, please open an issue against this repo.
+
+If you have suggestions or ideas, please write them up and add them to the "SUGGESTION-BOX" folder of this repo (via pull request).  This way we can share the ideas with the community and crowdsource for feature delivery.
+
+Thank you!

data/docs/Providers/IPports.md

@@ -0,0 +1,61 @@
+# Junos::Ez::IPports::Provider
+
+Manages IPv4 ports.  For now, ports recognized are:
+
+  - Fast Ethernet: `fe-*`
+  - Gigabit Ethernet: `ge-*`
+  - 10 Gigabit Ethernet: `xe-*`
+
+IPv6 ports are a different provider (comming soon...)
+
+# USAGE
+
+The provider *name* selector is the interface.  If the *name* does not include the ".0" unit, the framework will default to this.
+
+```ruby
+Junos::Ez::IPports::Provider( ndev, :ip_ports )
+
+port = ndev.ip_ports["ge-0/0/8"]
+
+puts "IPv4 port #{port.name} does not exist!" unless port.exists?
+```
+
+# PROPERTIES
+
+  - `:admin` - [:up, :down] - administrative control of the port
+  - `:description` - String, description assigned at the interface unit level
+  - `:tag_id` - Fixnum, used if the phyiscal port is vlan-tagging (but not L2port)
+  - `:mtu` - Fixnum, MTU value assigned for IP packets (but not L1port MTU)
+  - `:address` - String in "ip/prefix" format.  For example "192.168.10.12/24"
+  - `:acl_in` - Name of input ACL (firewall-filter)
+  - `:acl_out` - Name of output ACL
+
+# METHODS
+
+## status
+
+Returns a Hash of status information about the IP unit interface.
+```ruby
+port = ndev.ip_ports["ge-0/0/8.0"]
+
+# display the configuration information
+pp port.to_h
+-> 
+{"ge-0/0/8.0"=>
+  {:_active=>true,
+   :_exist=>true,
+   :admin=>:up,
+   :description=>"this is port8",
+   :address=>"192.168.100.1/24",
+   :acl_in=>"foo",
+   :acl_out=>"bar"}}
+
+# display the status information
+pp port.status
+-> 
+{:l1_oper_status=>:up,
+ :oper_status=>:up,
+ :snmp_index=>522,
+ :packets_rx=>0,
+ :packets_tx=>18}
+```

data/docs/Providers/L1ports.md

@@ -0,0 +1,29 @@
+# Junos::Ez::L1ports::Provider
+
+Manages the physical properties of interfaces.
+
+# USAGE
+
+The provider *name* selector is the interface name.
+
+```ruby
+Junos::Ez::L1ports::Provider( ndev, :l1_ports )
+
+port = ndev.l1_ports["ge-0/0/12"]
+
+port[:admin] = :down
+port.write!
+```
+
+# PROPERTIES
+
+  - `:admin` - [:up, :down] - administratively controls the port
+  - `:description` - String, description applied at the physical port
+  - `:mtu` - Fixnum, MTU value applied at the physical port
+  - `:speed` - Link Speed, [:auto, '10m', '100m', '1g', 10g']
+  - `:duplex` - Link Duplex, [:auto, :half, :full]
+  - `:unit_count` - **READ-ONLY** indicates the number of logical ports (units) configured
+
+# METHODS
+
+No additional methods at this time ...

data/docs/Providers/L2ports.md

@@ -0,0 +1,43 @@
+# Junos::Ez::L2ports::Provider
+
+Manages the ethernet switch ports.  The primary function is to associate switching ports to VLANs.
+
+Currently the association of VLANS to ports is read/write under the interfaces stanza.  Junos OS also supports
+the association under the VLAN resource stanza (vlans/bridge-domains).  
+
+_NOTE: this provider does not use the VLAN resource stanza at this time.  Under review now.  If you have an opionin on this, please let us know, thank you!_ 
+
+# USAGE
+
+The provider *name* is the interface.  The framework will assume unit 0 if the name does not indicate one.
+
+```ruby
+Junos::Ez::L2ports::Provider( ndev, l2_ports )
+
+port = ndev.l2_ports["ge-0/0/12"]
+
+puts "port #{port.name} is not a switch-port!" unless port.exists?
+```
+
+# PROPERTIES
+
+  - `:description` - String description at the logical interface level
+  - `:untagged_vlan` - String, VLAN-name for packets without VLAN tags
+  - `:tagged_vlans` - Array of VLAN-names for packets with VLAN tags
+  - `:vlan_tagging` - [true | false] - indicates if this port accepts packets with VLAN tags
+
+# METHODS
+
+No additional methods at this time ...
+
+# SUPPORTED PLATFORMS
+
+  - EX2200, EX3200, EX3300, EX4200, EX4500, EX4550, EX6100, EX8200
+  - SRX branch: **entire product line, but not vSRX**
+  - QFX3500, QFX3600
+  
+Comming soon:
+
+  - EX platforms released in 2013
+  - MX5, MX10, MX40, MX80, MX240, MX480, MX960
+

data/docs/Providers/StaticHosts.md

@@ -0,0 +1,26 @@
+# Junos::Ez::StaticHosts::Provider
+
+Manages locally configured host-name to IPv4 & IPv6 address mapping
+
+# USAGE
+
+The provider *name* is the host-name as it would have been configured under `[edit system static-host-mapping]`
+
+```ruby
+Junos::Ez::StaticHosts::Provider( ndev, :etc_hosts )
+
+host = ndev.etc_hosts["ex4.jeremylab.net"]
+host[:ip] = "192.168.10.24"
+host.write!
+```
+
+# PROPERITES
+
+  - `:ip` - The IPv4 address
+  - `:ip6` - The IPv6 address
+
+_NOTE: A host entry **can** have both IPv4 and IPv6 addresses assigned at the same time_
+
+# METHODS
+
+No additional methods at this time ...

data/docs/Providers/StaticRoutes.md

@@ -0,0 +1,37 @@
+# Junos::Ez::StaticRoutes::Provider
+
+Manages static route entries.
+
+_NOTE: for now, routing-instances are not supported, but under review for upcoming release..._
+
+# USAGE
+
+The provider *name* is the target-route.  If you want to specify the default-route, you can either use "0.0.0.0/0" or the special name `:default`.
+
+```ruby
+Junos::Ez::StaticRoutes::Provider( ndev, :route )
+
+default = ndev.route[:default]
+
+unless default.exists?
+  default[:gateway] = "192.168.1.1"
+  default.write!
+end
+```
+
+# PROPERTIES
+
+  - `:gateway` - The next-hop gateway.  Could be single String or Array-of-Strings
+  - `:metic` - The metric assigned to this route, Fixnum
+  - `:action` - Configures the route action, [:reject, :discard, :receive]
+  - `:active` - Configures the route active, [true, false, nil]
+  - `:retain` - Configures the ratain/no-retain flag, [ nil, true, false ]
+  - `:install` - Configures the install/no-install flag, [nil, true, false ]
+  - `:readvertise` - Configures the readvertise/no-readvertise flag, [nil, true, false]
+  - `:resovlve` - Configures the resolve/no-resolve falg, [nil, true, false]
+
+In the above "flag controls", assigning the values [true | false] configures if the flat is set or "no-" set respectively.  To delete the flag from the configuration, set the property to `nil`.
+
+# METHODS
+
+No additional methods at this time ...

data/docs/Providers/UserAuths.md

@@ -0,0 +1,32 @@
+# Junos::Ez::UserAuths::Provider
+
+Manages user account ssh-keys, RSA or DSA.  
+
+# USAGE
+
+The provider *name* for accessing the provider is a Hash comprised of the following key/value pairs:
+
+  - `:user` - String, user-name
+  - `:keytype` - String, one of ['ssh-rsa', 'ssh-dsa']
+  - `:publickey` - String, the public key value
+
+```ruby
+
+# bind :auths for managing ssh-keys directly
+
+Junos::Ez::UserAuths::Provider( ndev, :auths )
+
+# setup a name Hash to access this key
+
+key_name = {}
+key_name[:user] = "jeremy"
+key_name[:keytype] = "ssh-rsa"
+key_name[:publickey] = "ssh-rsa gibberishMagicSwingDeadCatoverHeadand_LetMeLoginFoo"
+
+ssh_key = ndev.auths[ key_name ]
+
+puts "Key does not exist" unless ssh_key.exists?
+```
+
+Generally speaking, you probably won't be using this provider directly, but rather using a 
+`Junos::Ez::Users::Provider` resource and the `load_ssh_key!` method.  This method makes use of the `Junos::Ez::UserAuths::Provider` internally.

data/docs/{Users.md → Providers/Users.md}

@@ -2,6 +2,21 @@
 
 Manages the on-target configured users, located under Junos `[edit system login]` stanza. 
 
+# USAGE
+
+The provider *name* selector is the user-name String.
+
+```ruby
+
+# bind :users to provide access to the local login configuration
+
+Junos::Ez::Users::Provider( ndev, :users )
+
+user = ndev.users["jeremy"]
+
+puts "#{user.name} does not exist!" unless user.exists?
+```
+
 # PROPERTIES
 
   - `:class` - String, The user priviledge class (like "read-only", or "super-user")
@@ -12,6 +27,8 @@ Manages the on-target configured users, located under Junos `[edit system login]
 
 If you need to modify the user's ssh-keys, see the `load_ssh_key!` method in the next section.
 
+
+
 # RESOURCE METHODS
 
 ## password=

data/docs/Providers/Vlans.md

@@ -0,0 +1,43 @@
+# Junos::Ez::Vlans::Provider
+
+Manages Ethernet VLANs.
+
+If you are looking for associating ethernet-ports to VLANs, please refer to the `Junos::Ez::L2ports::Provider` documentation.
+
+# USAGE
+
+The provider *name* selector is the vlan-name, String. 
+
+```ruby
+Junos::Ez::Vlans::Provider( ndev, :vlans )
+
+vlan = ndev.vlans["Blue"]
+
+puts "VLAN: #{vlan.name} does not exists!" unless vlan.exists?
+```
+
+# PROPERTIES
+
+  - `:vlan_id` - The VLAN tag-id, Fixnum [ 1 .. 4094]
+  - `:description` - String description for this VLAN
+  - `:no_mac_learning` - If `true` this VLAN will not learn MAC addresses
+
+# RESOURCE METHODS
+
+## interfaces
+
+This method will return a Hash structure of interfaces bound to this VLAN.
+```ruby
+ndev.vlans["Green"].interfaces
+-> 
+{"ge-0/0/22"=>{:mode=>:trunk},
+ "ge-0/0/0"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/1"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/2"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/3"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/5"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/6"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/7"=>{:mode=>:trunk, :native=>true},
+ "ge-0/0/20"=>{:mode=>:access},
+ "ge-0/0/21"=>{:mode=>:access}}
+```

data/docs/Providers_Resources.md

@@ -288,6 +288,17 @@ end
 The above example will also return the new resource object.   So you could use the Ruby
 block as a default initializer, and then continue to make changes to the resource.  
 
+The `create` method takes an optional 2nd argument, a Hash of the resource properties.  So you could do the following equivalent:
+
+```ruby
+data = {:description => "I am port 20", :untagged_vlan => "Blue" }
+
+ndev.l2_ports.create('ge-0/0/20', data) do |port|
+   port.write!
+   port.deactivate!
+end
+```
+
 The second way is to simply select a resource by name that doesn't exist.  So let's
 say you want to create a new L2port for `ge-0/0/20`.  It would look something like this:
 
@@ -300,3 +311,16 @@ port[:description] = "I am port 20"
 port[:untagged_vlan] = "Storage"
 port.write!
 ```
+
+### Interating Resources
+
+You can use the `each` method to interate through each managed resource.  For example:
+
+```ruby
+ndev.l1_ports.each do |port|
+  status = port.status
+  if (port[:admin] == :up) and (status[:oper_status] != :up)
+    puts "Port #{port.name} should be up, and isn't!
+  end
+end
+```

data/docs/README_FIRST.md

@@ -0,0 +1,27 @@
+# CODE EXAMPLES
+
+Much of the documentation include small code "snippets".  These are not complete programs, but rather meant to show specific functionality.  
+
+The following libraries are assumed to be in scope:
+
+  - `require 'pp'` : for pretty-printing Ruby objects
+  - `require 'pry'` : for setting code break-points
+
+These examples use the `->` symbol to indicate screen output.  For example:
+
+```ruby
+
+port = ndev.l2_ports["ge-0/0/8"]
+pp port.to_h
+->
+{"ge-0/0/0"=>
+  {:_active=>true,
+   :_exist=>true,
+   :description=>"Jeremy port for testing",
+   :vlan_tagging=>true,
+   :untagged_vlan=>"Green",
+   :tagged_vlans=>["Red"]}}
+
+```
+
+Here the Hash structure following the `->` is the output of the prior "pretty-print", `pp port.to_h`, instruction.

data/docs/Utils/Config.md

@@ -0,0 +1,161 @@
+# Junos::Ez::Config::Utils
+
+A collection of methods to perform file / template based configuration, and configuration control functions, like "commit", "show | compare", "rollback", etc.
+
+These methods return data in Hash / Array structures so the information can be programmatically accessible, rather than scraping CLI or navigating Junos XML.
+
+# USAGE
+
+```ruby
+# bind :cu to give us access to the config utilities
+Junos::Ez::Config::Utils( ndev, :cu )
+
+# load a Junos configuration file on our local filesys
+
+ndev.cu.load! :filename => 'basic-setup.conf'
+
+# check to see if these changes will commit ok.  if not, display the errors, rollback the config,
+# close the netconf session, and exit the program.
+
+unless (result = ndev.cu.commit?) == true
+  puts "There are commit errors, dumping result ..."
+  pp result
+  ndev.cu.rollback!
+  ndev.close
+  exit 1
+end
+
+# commit the confguration and close the netconf session
+
+ndev.cu.commit!
+ndev.close
+```
+
+# METHODS
+
+  - `lock!` - attempt exclusive config, returns true or raises Netconf::LockError
+  - `load!` - loads configuration snippets or templates (ERB)
+  - `diff?` - returns String of "show | compare" as String
+  - `commit?` - checks the candidate config for validation, returns true or Hash of errors
+  - `commit!` - performs commit, returns true or raises Netconf::CommitError 
+  - `unlock!` - releases exclusive lock on config
+  - `rollback!` - performs rollback of config
+  - `get_config` - returns text-format of configuration
+
+# GORY DETAILS
+
+## lock!
+Attempt exclusive config, returns `true` if you now have the lock, or raises `Netconf::LockError` exception if the lock is not available
+
+## load!( opts = {} )
+
+Loads configuration snippets or templates (ERB).  This method does **not** commit the change, only loads the contents into the candidate configuration.  If the load was successful, this method will return `true`. Otherwise it will raise a `Netconf::EditError` exception.
+
+The options Hash enables the following controls:
+
+
+```
+:filename => String
+```
+Identifies filename on local-system.  File can contain either static config or template in ERB format. The framework will identify the format-style of the content by the filename extension.  You can override this behavior using the `:format` option.  By default, the framework will map extensions to `:format` as follow:
+
+  - `:text` when *.{conf,text,txt}
+  - `:set` when *.set
+  - `:xml` when *.xml
+
+```
+:content => String
+```
+Ccontent of configuration, rather than loading it from a file.  Handy if you are loading the same content on many devices, and you don't want to keep re-reading it from a file
+
+```
+:format => Symbol
+```
+
+Identifies the format-style of the configuration.  The default is `:text`.  Setting this option will override the `:filename` extension style mapping.
+
+  `:text` - indcates "text" or "curly-brace" style
+  
+  `:set` - "set" commands, one per line
+  
+  `:xml` - native Junos XML
+      
+```
+:binding => Object | Binding
+``` 
+Required when the configuration content is a Ruby ERB template.  If `:binding` is an Object, then that object becomes the scope of the variables available to the template.  If you want to use the *current scope*, then using the `binding` variable that is availble (it is always there)  
+
+```  
+:overwrite!
+```
+When `true` the provided configuraiton will **COMPLETELY OVERWRITE** any existing configuration.  This is useful when writing an entire configuration from scratch.
+
+```
+:replace! 
+```
+When `true` enables the Junos *replace* option.  This is required if your configuration changes utilize either the `replace:` statement in text-format style or the `replace="replace"` attribute in XML-format style.  You do not need to set this option if you are using the set-format style.
+
+## diff?
+Returns String of "show | compare" as String.  If there is no diff, then this method returns `nil`.
+
+## commit?
+
+Checks the candidate config for validation, returns `true` or Array of errors.
+
+The following is an example errors:
+```ruby
+ndev.cu.commit?
+->
+[{:severity=>"error",
+  :message=>"Referenced filter 'foo' is not defined",
+  :edit_path=>"[edit interfaces ge-0/0/8 unit 0 family inet]",
+  :bad_identifier=>"filter"},
+ {:severity=>"error", :message=>"configuration check-out failed"}]
+```
+
+## commit!( opts = {} )
+
+Performs commit, returns `true` or raises `Netconf::CommitError`.  Available options are:
+
+    :comment => String
+A commit log comment that is available when retrieving the commit log.
+
+    :confirm => Fixnum-Minutes
+Identifies a timeout in minutes to automatically rollback the configuration unless you explicitly issue another commit action.  This is very useful if you think your configuration changes may lock you out of the device.
+
+## unlock! 
+
+Releases exclusive lock on config.  If you do not posses the lock, this method will raise an `Netconf::RpcError` exception.
+
+## rollback!( rollback_id = 0 )
+
+Loads a rollback of config, does not commit.
+
+## get_config( scope = nil )
+
+Returns the text-style format of the request config.  If `scope` is `nil` then the entire configuration is returned.  If the `scope` is invalid (asking for the "foo" stanza for example), then a string with "ERROR!" is returned.  If the requested config is non-existant (asking for non-existant interface), then `nil` is returned.
+
+Successful request:
+```ruby
+puts ndev.cu.get_config "interfaces ge-0/0/0"
+->
+unit 0 {
+    family inet {
+        address 192.168.56.2/24;
+    }
+}
+```
+
+Valid request, but not config:
+```ruby
+puts ndev.cu.get_config "interfaces ge-0/0/3"
+-> 
+nil
+```
+
+Invalid request:
+```ruby
+puts ndev.cu.get_config "foober jazzbot"
+->
+ERROR! syntax error: foober
+```