shopify-junos-ez-stdlib 1.0.0

data/docs/Providers/Group.md

@@ -0,0 +1,61 @@
+# Junos::Ez::Group::Provider
+
+Manages JUNOS group properties
+
+# EXAMPLE
+
+The provider *name* selector is the JUNOS group name, e.g. "service_group".
+
+```ruby
+Junos::Ez::Group::Provider( ndev, :group )
+
+grp = ndev.group["service_group"]
+
+grp[:format] = 'set'
+grp[:path] = 'services.set'
+
+grp.write!
+
+```
+
+# PROPERTIES
+
+  - `:format` - JUNOS configuration format is file. It can be 'xml', 'text' or 'set'. Default is 'xml'
+  - `:path` - Path of configuration file that is applied inside JUNOS group hierarchy.
+
+# METHODS
+
+No additional methods at this time ...
+
+# USAGE NOTES
+
+Contents of 'service.set' file
+
+````
+% cat services.set 
+set system services ftp
+set system services ssh
+set system services netconf ssh
+````
+
+JUNOS group configuration reflected on executing above example.
+
+````
+{master}[edit]
+junos@switch# show groups service_group 
+system {
+    services {
+        ftp;
+        ssh;
+        netconf {
+            ssh;
+        }
+    }
+}
+
+junos@switch# show apply-groups
+apply-groups [ global re0 re1 service_group ];
+
+````
+
+

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` - Set 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/LAGports.md

@@ -0,0 +1,57 @@
+# Junos::Ez::LAGports::Provider
+
+Manages Link Aggregation Group (LAG) port properties
+
+# EXAMPLE
+
+The provider *name* selector is the interface name, e.g. "ae0".
+
+```ruby
+Junos::Ez::LAGports::Provider( ndev, :lags )
+
+port = ndev.lags["ae0"]
+
+port[:links] = ["ge-0/0/0", "ge-0/0/1", "ge-0/0/2", "ge-0/0/3"]
+port[:lacp] = :active
+port[:minimum_links] = 2
+
+port.write!
+```
+
+# PROPERTIES
+
+  - `:links` - Set of interface names
+  - `:lacp` - [:active, :passive, :disabled], :disabled is default
+  - `:minimum_links` - number of interfaces that must be active for LAG to be declared 'up'
+
+# METHODS
+
+No additional methods at this time ...
+
+# USAGE NOTES
+
+### Allocating Aggregated Ethernet (AE) Ports in Junos
+
+Before using LAG ports, you must first configured the "aggregated ethernet ports" device count in Junos.  This is done under the `[edit chassis]` stanza as shown:
+
+````
+{master:0}[edit chassis]
+jeremy@switch# show
+aggregated-devices {
+    ethernet {
+        device-count 10;
+    }
+}
+````
+
+### Changing the Links Property
+
+The `:links` property is internally managed as a Ruby Set.  When modifing the `:links` property you must use an Array notation, even if you are simply adding or removing one link. For example:
+
+````ruby
+port = ndev.lags["ae0"]
+
+port[:links] += ["ge-0/0/15"]
+port.write!
+````
+

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/Providers/Users.md

@@ -0,0 +1,122 @@
+# Junos::Ez::Users::Provider
+
+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")
+  - `:uid` - Number, User ID (unix).  If not provided, Junos will auto-create
+  - `:fullname` - String, User Full Name
+  - `:password` - Junos encrypted password
+  - `:ssh_keys` - SSH keys (READ/ONLY)
+
+If you need to modify the user's ssh-keys, see the `load_ssh_key!` method in the next section.
+
+
+
+# RESOURCE METHODS
+
+## password=
+
+Used to set the user password by providing a plain-text value.
+```ruby
+
+Junos::Ez::User::Provider( ndev, :users )
+
+pp ndev.users.list
+-> 
+["goofy", "jeremy"]
+
+user = ndev.users["goofy"]
+user.to_h
+-> 
+{"goofy"=>
+  {:_active=>true,
+   :_exist=>true,
+   :uid=>"3000",
+   :class=>"read-only",
+   :password=>"XRykM8Grm0R0A"}}
+
+# set the password with plaintext value, then re-read the config from the device
+user.password = "n3wpassw0rd"
+user.read!
+
+user.to_h
+->
+{"goofy"=>
+  {:_active=>true,
+   :_exist=>true,
+   :uid=>"3000",
+   :class=>"read-only",
+   :password=>"W05ckLnjLcPCk"}}
+```
+## load_ssh_key!( :opts = {} )
+
+    opts[:publickey] - String of public-key
+    opts[:filename] - String, filename on server to public-key file
+
+This method will create an ssh-key for the user based on the contents of the provided public key.  The key will be written to the device, but not committed (just like resource write!).  The `Junos::Ez::UserAuths::Provider` resource for this key will be returned.
+
+```ruby
+user = ndev.users["jeremy"]
+pp user.to_h
+->
+{"jeremy"=>
+  {:_active=>true,
+   :_exist=>true,
+   :uid=>"2008",
+   :class=>"super-user",
+   :password=>"$1$JhZms6TE$dXF8P1ey1u3G.5j/V9FBk0"}}
+
+# write the key and then re-load user object
+user.load_ssh_key! :filename=>'/home/jschulman/.ssh/keys/key1.pub'
+user.read!
+pp user.to_h
+->
+{"jeremy"=>
+  {:_active=>true,
+   :_exist=>true,
+   :uid=>"2008",
+   :class=>"super-user",
+   :password=>"$1$JhZms6TE$dXF8P1ey1u3G.5j/V9FBk0",
+   :ssh_keys=>
+    {"ssh-rsa"=>
+      ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDIpOXEUJFfHstdDjVEaTIf5YkTbUliSel6/dsNe"]}}}
+```
+## ssh_key( keytype, index = 0 )
+    keytype: ['ssh-rsa', 'ssh-dsa']
+
+This method will return a formulate name Hash for the specified key.  This name can then be used in conjunction 
+with the `Junos::Ez::UserAuth::Provider` class.
+
+The `index` parameter is used to select a key in the event that there is more than one in use.
+
+```ruby
+key_name = user.ssh_key( 'ssh-rsa' )
+->
+{:user=>"jeremy",
+ :keytype=>"ssh-rsa",
+ :publickey=>
+  "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDIpOXEUJFfHstdDjVEaTIf5YkTbUliSel6/dsNe"}
+
+# bind :auths as so we can directly access ssh-keys ...
+Junos::Ez::UserAuths::Provider( ndev, :auths )
+
+# now delete the key from the user.
+ndev.auths[ key_name ].delete!
+```