ruby-jss 0.6.7 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84de41e5f3101ed3bf86feb96016d34cb92ed9f7
-  data.tar.gz: 3dcde380f730a98fa04dfa64e8af60a7dda3c1eb
+  metadata.gz: 0b5245057f32987e52e0753f330b6b2fdd3b5a26
+  data.tar.gz: 8028f472e0694cfc2dd1fbf93914369482fdddd5
 SHA512:
-  metadata.gz: 4566f6731f57ea24c99814fe43552fc20816a941e57155d1d6c9012af5ab74e7f81849287f53f514eff179e5e4dd7b94c57cd8c9f4c30b5391c88735a831771b
-  data.tar.gz: 1d04c57374e60a2c1d8989e302196aef07468ba6a6d3b6d467043c2b08d6c218801ce072b61fc1bcedea84a2689725d1a22e00335f917415ead177cb01f6c8f9
+  metadata.gz: c4b8aaa54395cf65ccd910b15694edef02d70899169ef3f433f61721b2729d5b7af31558990bb88e2b48ef829079cf2f0bcf81fbe49f463059977e4ff39aef84
+  data.tar.gz: 8577fd4833e3f93c6582612210ca63dd2ec9da3249f1e199f1471c12569b5e7bdd247e42d1acb818f779a06ef57b5f7c97906995a1717c9548b906a1f44fceea

data/CHANGES.md

@@ -1,5 +1,11 @@
 # Change History
 
+## v0.7.0 2017-02-01
+
+- JSS::NetworkSegment - many bugfixes and cleanup. I didn't really have a proper grasp of IP CIDR masks before and how the (don't) related to the IP ranges used by Network Segments in the JSS. They CIDRs and full netmasks can still be used to set the ending addresses of NetworkSegment objects, but the #cidr method is gone, since it was meaningless for segments that didn't match subnet-ranges.
+- subnect-update, the example command in the bin directory, has been renamed to negseg-update. It's also been cleaned up and uses the new functionality of JSS::NetworkSegment.
+- JSS::DBConnection - fixed a bug where meaningless IO 'stream closed' errors would appear when closing the DB connection.
+
 ## v0.6.7 2017-01-03
 
 - Added class JSS::WebHook, which requires Jamf Pro 9.97 or higher.

data/bin/jss-webhook-server

@@ -0,0 +1,3 @@
+#!/usr/bin/ruby
+require 'jss/webhooks/server_app'
+JSSWebHooks::Server.run!

data/bin/netseg-update

@@ -0,0 +1,387 @@
+#!/usr/bin/ruby
+
+### Copyright 2017 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+
+# == Synopsis
+#   Add, remove, or change the Network Segments in the JSS based on data from an input file
+#   in CSV, tab, or other delimited format.
+#
+# == Usage
+#   subnet-update [-t | -d delimiter] [-h] file
+#
+#
+# == Author
+#   Chris Lasell <chrisl@pixar.com>
+#
+# == Copyright
+#   Copyright (c) 2014 Pixar Animation Studios
+##############################
+
+# Libraries
+##############################
+require 'ruby-jss'
+require 'getoptlong'
+require 'english'
+load '/Users/chrisl/git/gemdev/ruby-jss/lib/jss/api_object/network_segment.rb'
+
+# The app object
+##############################
+class App
+
+  # Constants
+  ##############################
+
+  PROG_NAME = File.basename($PROGRAM_NAME)
+
+  USAGE = "Usage: #{PROG_NAME} [options] [--help] /path/to/file".freeze
+
+  POTENTIAL_COLUMNS = %i(name starting ending cidr mask).freeze
+
+  DEFAULT_CACHE_FILE = Pathname.new('~/.last_subnet_update').expand_path
+
+  DEFAULT_DELIMITER = "\t".freeze
+
+  DEFAULT_COLUMNS = [:name, :starting, :ending].freeze
+
+  DEFAULT_MANUAL_PREFIX = 'Manual-'.freeze
+
+  # define the cli opts
+  CLI_OPTS = GetoptLong.new(
+    ['--help', '-H', GetoptLong::NO_ARGUMENT],
+    ['--delimiter', '--delim', '-d', GetoptLong::REQUIRED_ARGUMENT],
+    ['--header', '-h', GetoptLong::NO_ARGUMENT],
+    ['--columns', '-c', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--manual-prefix', '-m', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--cache', GetoptLong::REQUIRED_ARGUMENT],
+    ['--debug', GetoptLong::NO_ARGUMENT],
+    ['--server', '-S', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--port', '-P', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--user', '-U', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--no-verify-cert', '-V', GetoptLong::NO_ARGUMENT],
+    ['--timeout', '-T', GetoptLong::OPTIONAL_ARGUMENT],
+    ['--no-op', '-N', GetoptLong::NO_ARGUMENT]
+  )
+
+  attr_reader :debug
+
+  def initialize(_args)
+    @getpass = $stdin.tty? ? :prompt : :stdin
+    set_defaults
+    parse_cli
+    check_opts
+  end # init
+
+  def set_defaults
+    @debug = false
+    @delim = DEFAULT_DELIMITER
+    @header = false
+    @columns = DEFAULT_COLUMNS
+    @cache_file = DEFAULT_CACHE_FILE
+    @manual_prefix = DEFAULT_MANUAL_PREFIX
+    @user = JSS::CONFIG.api_username
+    @server = JSS::CONFIG.api_server_name
+  end
+
+  def parse_cli
+    # parse the cli opts
+    CLI_OPTS.each do |opt, arg|
+      case opt
+      when '--help' then show_help
+      when '--delimiter' then @delim = arg
+      when '--header' then @header = true
+      when '--columns' then @columns = arg.split(',').map(&:to_sym)
+      when '--manual-prefix' then @manual_prefix = arg
+      when '--cache' then @cache_file = Pathname.new arg
+      when '--debug' then @debug = true
+      when '--server' then @server = arg
+      when '--port' then @port = arg
+      when '--user'then @user = arg
+      when '--no-verify-cert' then @verify_cert = false
+      when '--timeout' then @timeout = arg
+      when '--no-op' then @noop = true
+      end # case
+    end # each opt arg
+    @columns = nil if @columns && @columns.empty?
+    @file = Pathname.new ARGV.shift.to_s
+  end # parse_cli
+
+  def check_opts
+    raise JSS::MissingDataError, 'No JSS Username provided or found in the JSS gem config.' unless @user
+    raise JSS::MissingDataError, 'No JSS Server provided or found in the JSS gem config.' unless @server
+    raise ArgumentError, "No input file specified.\n#{USAGE}" unless @file
+    raise  "Input file doesn't exist or is not readable: #{@file}" unless @file.readable?
+  end
+
+  # Go!
+  def run
+    unless data_file_changed?
+      puts "File hasn't changed since last time, no changes to make!"
+      return
+    end
+
+    connect_to_jss
+
+    @parsed_data = parse_file
+
+    update_network_segments
+    cache_latest_data
+  end # run
+
+  def connect_to_jss
+    JSS::API.connect(
+      server: @server,
+      port: @port,
+      verify_cert: @verify_cert,
+      user: @user,
+      pw: @getpass,
+      stdin_line: 1,
+      timeout: @timeout
+    )
+  end
+
+  def show_help
+    puts <<-FULLHELP
+Update the JSS Network Segments from a delimited file of subnet information.
+CAUTION: This script can delete Network Segments from your JSS.
+  See the --no-op option
+#{USAGE}
+
+Options:
+ -d, --delimiter        - The field delimiter in the file, defaults to tab.
+ -c, --columns [col1,col2,col3]
+                        - The column order in file, must include 'name', 'starting',
+                            and either 'ending', 'mask', or 'cidr'
+ -h, --header           - The first line of the file is a header line,
+                            defining the columns
+ -m, --manual-prefix    - Network Segment names in the file and the JSS with this
+                            prefix are ignored. Defaults to 'Manual-'
+ --cache /path/..       - Where read/save the input data for comparison between runs.
+                            Defaults to ~/.last_subnet_update
+ -S, --server srvr      - specify the JSS API server name
+ -P, --port portnum     - specify the JSS API port
+ -U, --user username    - specify the JSS API user
+ -V, --no-verify-cert   - Allow self-signed, unverified SSL certificate
+ -T, --timeout secs     - specify the JSS API timeout
+ -N, --no-op            - Don't make any changes in the JSS, just report what would
+                          have be changed.
+ -H, --help             - show this help
+ --debug                - show the ruby backtrace when errors occur
+
+This program parses the input file line by line (possibly accounting for a header line).
+Each line defines the name and IP-range of a network segment.
+
+- If a segment in the file doesn't exist in the JSS, it is created in the JSS.
+- If a segment's range is different in the file, it is updated in the JSS.
+- If a segment in the JSS doesn't exist in the file, it is deleted from the JSS.
+
+Any network segments with names starting with the given --manual-prefix are ignored.
+The default manual-prefix is 'Manual-'  so, e.g. segments named 'Manual-isolated'
+and 'Manual-special-servers' in the JSS won't be touched.
+
+Input File:
+  - The file must contain three columns, separated by the --delimiter,
+    with these names, in any order:
+    - 'name'  (the network segment name)
+    - 'starting' (the starting IP address of the network segment)
+    - ONE of:
+      - 'ending' (the ending IP address of the network segment)
+      - 'cidr'  (the network range of the segment as a CIDR bitmask, e.g. '24')
+      - 'mask'  (the network range of the segment as an IP mask, e.g. '255.255.255.0')
+Notes:
+ - The --columns option is a comma-separted list of the three
+   column names above indicating the column-order in the file.
+
+ - If --columns are not provided, and --header is specified, the first line
+  is assumed to contain the column names, separated by the delimiter
+
+ - If --header is provided with --columns, the first line of the file is ignored.
+
+ - The raw data from the file is cached and compared to the input file at
+   the next run. If the data is identical, no changes are made.
+
+ - If no API connection settings are provided, they will be read from
+   /etc/ruby-jss.conf and ~/.ruby-jss.conf. See the ruby-jss docs for details.
+
+ - The password for the connection will be read from STDIN or prompted if needed
+
+    FULLHELP
+    exit 0
+  end
+
+  # parse the incoming data file into an Hash of Hashes,
+  # Top level keys are the NetSeg names,
+  # Subhashes have keys :starting, and :ending
+  # Exclude any with names starting with @manual_prefix
+  #
+  # @return [Hash<Hash>] The lines of the file, as hashes
+  #
+  def parse_file
+    puts 'Parsing the data file'
+    # split the data into an array by newline/return chars.
+    # this means files saved by excel or windows will work.
+    lines = @raw_data.split(/[\n\r]+/)
+
+    # remove the first line if its a header, and parse it into the columns
+    # if needed
+    if @header
+      header = lines.shift
+      @columns ||= header.split(/\s*#{@delim}\s*/).map(&:to_sym)
+    end
+
+    check_columns
+
+    parsed_data = {}
+    lines.each do |line|
+      parsed_line = parse_a_data_line line
+      next unless parsed_line
+      name = parsed_line.delete :name
+      parsed_data[name] = parsed_line
+    end
+    parsed_names = parsed_data.keys
+    jss_names = JSS::NetworkSegment.all_names.reject { |jss_name| jss_name.start_with? @manual_prefix }
+    @segments_to_add = parsed_names - jss_names
+    @segments_to_delete = jss_names - parsed_names
+    @segments_to_check_for_changes = parsed_names - @segments_to_add - @segments_to_delete
+    parsed_data
+  end # parse_file
+
+  def check_columns
+    raise "Columns must include 'name' and 'starting'" unless \
+      @columns.include?(:name) && \
+      @columns.include?(:starting)
+    raise "Columns must include either 'ending', 'cidr', or 'mask'" unless \
+      @columns.include?(:ending) || \
+      @columns.include?(:cidr) || \
+      @columns.include?(:mask)
+    @use_cidr = (@columns.include?(:cidr) || @columns.include?(:mask))
+  end
+
+  def parse_a_data_line(line)
+    parts = line.split(@delim).map(&:strip)
+    name = parts[@columns.index(:name)]
+    starting = parts[@columns.index(:starting)]
+    ending = parts[@columns.index(:ending)]
+    unless name && starting && ending
+      puts "Skipping invalid line: #{line}"
+      return nil
+    end
+    if name.start_with? @manual_prefix
+      puts "Ignoring line with manual_prefix: #{line}"
+      return nil
+    end
+    { name: name, starting: starting, ending: ending }
+  end
+
+  def data_file_changed?
+    # read in the file
+    @raw_data = @file.read
+    return true unless @cache_file.exist?
+    @raw_data != @cache_file.read
+  end
+
+  def cache_latest_data
+    return if @noop
+    @cache_file.jss_save @raw_data
+  end
+
+  def update_network_segments
+    puts 'Applying changes'
+    add_segments
+    delete_segments
+    update_segments
+    puts 'Done!'
+  end # update_network_segments
+
+  def add_segments
+    @segments_to_add.each do |seg|
+      seg_data = @parsed_data[seg]
+      if @noop
+        connector = @use_cidr ? '/' : '->'
+        puts "Without --no-op this would: Add segment named '#{seg}', #{seg_data[:starting]}#{connector}#{seg_data[:ending]}"
+        next
+      end # if noop
+
+      ender = @use_cidr ? :cidr : :ending_address
+      new_seg = JSS::NetworkSegment.new(
+        :id => :new,
+        :name => seg,
+        :starting_address => seg_data[:starting],
+        ender => seg_data[:ending]
+      )
+      new_seg.create
+      puts "Added Network Segment '#{new_seg.name}' to the JSS"
+    end #  @segments_to_add.each do |seg|
+  end # add_segments
+
+  def delete_segments
+    @segments_to_delete.each do |seg|
+      if @noop
+        puts "Without --no-op this would: Delete segment named '#{seg}',"
+        next
+      end # if noop
+      JSS::NetworkSegment.new(name: seg).delete
+      puts "Deleted Network Segment '#{seg}' from the JSS"
+    end #  @segments_to_delete.each do |seg|
+  end # delete_segments
+
+  def update_segments
+    @segments_to_check_for_changes.each do |seg|
+      seg_data = @parsed_data[seg]
+      data_start = IPAddr.new(seg_data[:starting])
+      data_end = if @use_cidr
+                   IPAddr.new("#{seg_data[:starting]}/#{seg_data[:ending]}").to_range.end.mask 32
+                 else
+                   IPAddr.new(seg_data[:ending])
+                 end
+
+      this_seg = JSS::NetworkSegment.new name: seg
+      data_range = data_start..data_end
+      next if this_seg.range == data_range
+
+      if @noop
+        connector = @use_cidr ? '/' : '->'
+        puts "Without --no-op this would: Update segment named '#{seg}', #{seg_data[:starting]}#{connector}#{seg_data[:ending]}"
+        next
+      end # if noop
+
+      this_seg.set_ip_range starting_address: data_start, ending_address: data_end
+      this_seg.save
+      puts "Updated Network Segment '#{seg}' to range #{data_start} - #{data_end}"
+    end # @segments_to_check_for_changes.each do |seg|
+  end # update segments
+
+end # app
+
+##############################
+# create the app and go
+begin
+  debug = ARGV.include? '--debug'
+  app = App.new(ARGV)
+  app.run
+rescue
+  # handle exceptions not handled elsewhere
+  puts "An error occurred: #{$ERROR_INFO}"
+  puts 'Backtrace:' if debug
+  puts $ERROR_POSITION if debug
+end

data/lib/jss/api_object/computer.rb

@@ -60,8 +60,13 @@ module JSS
   ### * ip_address
   ### * udid
   ### * mac_addresses
-  ### * location data from the Locatable module
-  ### * purchasing data from the Purchasable module
+  ### * location data via the Locatable module
+  ### * purchasing data via the Purchasable module
+  ### * Extension Attribute values via the Extendable module
+  ###   Note: as with other 'recon' generated values, Ext. Attrs.
+  ###   populated by scripts cannot be modified via the API.
+  ###   (the change would be overwritten the next time the machine
+  ###   did a recon)
   ###
   ### After making any changes, you must call #update to send those
   ### changes to the server.

data/lib/jss/api_object/network_segment.rb

@@ -1,63 +1,56 @@
 ### Copyright 2017 Pixar
 
-###  
+###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in
 ###    compliance with the Apache License and the following modification to it:
 ###    Section 6. Trademarks. is deleted and replaced with:
-###  
+###
 ###    6. Trademarks. This License does not grant permission to use the trade
 ###       names, trademarks, service marks, or product names of the Licensor
 ###       and its affiliates, except as required to comply with Section 4(c) of
 ###       the License and to reproduce the content of the NOTICE file.
-###  
+###
 ###    You may obtain a copy of the Apache License at
-###  
+###
 ###        http://www.apache.org/licenses/LICENSE-2.0
-###  
+###
 ###    Unless required by applicable law or agreed to in writing, software
 ###    distributed under the Apache License with the above modification is
 ###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ###    KIND, either express or implied. See the Apache License for the specific
 ###    language governing permissions and limitations under the Apache License.
-### 
+###
 ###
 
 ###
 module JSS
 
-  #####################################
   ### Module Variables
   #####################################
 
-  #####################################
   ### Module Methods
   #####################################
 
-  #####################################
   ### Classes
   #####################################
 
-  ###
   ### A Network Segment in the JSS
   ###
-  ### @see JSS::APIObject
   ###
-  class NetworkSegment  < JSS::APIObject
+  class NetworkSegment < JSS::APIObject
 
-    #####################################
     ### Mix Ins
     #####################################
     include JSS::Creatable
     include JSS::Updatable
     include Comparable
 
-    #####################################
     ### Class Constants
     #####################################
 
     ### the REST resource base
-    RSRC_BASE = "networksegments"
+    RSRC_BASE = 'networksegments'.freeze
 
     ### the hash key used for the JSON list output of all objects in the JSS
     RSRC_LIST_KEY = :network_segments
@@ -67,41 +60,124 @@ module JSS
     RSRC_OBJECT_KEY = :network_segment
 
     ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = [:distribution_point, :starting_address, :override_departments ]
-
-    #####################################
-    ### Class Variables
-    #####################################
-
-    @@network_ranges = nil
+    VALID_DATA_KEYS = [:distribution_point, :starting_address, :override_departments].freeze
 
-    #####################################
     ### Class Methods
     #####################################
 
+    ### All NetworkSegments in the jss as IPAddr object Ranges representing the
+    ### Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
+    ### the range looks like:
+    ###   <IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>
     ###
-    ### All NetworkSegments in the jss as IPAddr objects representing the
-    ### subnet as a masked IPv4 address.
-    ###
-    ### Using the #include? and #to_range methods on those
-    ### objects is very useful.
+    ### Using the #include? method on those Ranges is very useful.
     ###
-    ### @return [Hash{Integer => IPAddr}] the network segments as masked IPv4 addresses
+    ### @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
     ###
     def self.network_ranges(refresh = false)
-      @@network_ranges = nil if refresh
-      return @@network_ranges if @@network_ranges
-      @@network_ranges = {}
-      self.all.each{|ns| @@network_ranges[ns[:id]] =  IPAddr.jss_masked_v4addr(ns[:starting_address], ns[:ending_address])}
-      @@network_ranges
+      @network_ranges = nil if refresh
+      return @network_ranges if @network_ranges
+      @network_ranges = {}
+      all(refresh).each { |ns| @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address]) }
+      @network_ranges
     end # def network_segments
 
-    ###
     ### An alias for {NetworkSegment.network_ranges}
     ###
-    def self.subnets(refresh = false); self.network_ranges refresh; end
+    ### DEPRECATED: This will be going away in a future release.
+    ###
+    ### @see {NetworkSegment::network_ranges}
+    ###
+    def self.subnets(refresh = false)
+      network_ranges refresh
+    end
 
+    ### Given a starting address & ending address, mask, or cidr,
+    ### return a Range object of IPAddr objects.
+    ###
+    ### starting_address: must be provided, and may be a masked address,
+    ### in which case nothing else is needed.
+    ###
+    ### If starting_address: is an unmasked address, then one of ending_address:
+    ### cidr: or mask: must be provided.
+    ###
+    ### If given, ending_address: overrides mask:, cidr:, and a masked starting_address:
+    ###
+    ### These give the same result:
+    ###
+    ### ip_range starting_address: '192.168.1.0', ending_address: '192.168.1.255'
+    ### ip_range starting_address: '192.168.1.0', mask: '255.255.255.0'
+    ### ip_range starting_address: '192.168.1.0', cidr: 24
+    ### ip_range starting_address: '192.168.1.0/24'
+    ### ip_range starting_address: '192.168.1.0/255.255.255.0'
+    ###
+    ### All the above will produce:
+    ###    #<IPAddr: IPv4:192.168.1.0/255.255.255.255>..#<IPAddr: IPv4:192.168.1.255/255.255.255.255>
     ###
+    ### An exception is raised if the starting address is above the ending address.
+    ###
+    ### @param starting_address[String] The starting address, possibly masked
+    ###
+    ### @param ending_address[String] The ending address. If given, it overrides mask:,
+    ###  cidr: and a masked starting_address:
+    ###
+    ### @param mask[String] The subnet mask to apply to the starting address to get
+    ###   the ending address
+    ###
+    ### @param cidr[String, Integer] he cidr value to apply to the starting address to get
+    ###   the ending address
+    ###
+    ### @return [Range<IPAddr>] the valid Range
+    ###
+    def self.ip_range(starting_address: nil, ending_address: nil, mask: nil, cidr: nil)
+      raise JSS::MissingDataError, 'starting_address: must be provided' unless starting_address
+
+      starting_address = masked_starting_address(starting_address: starting_address, mask: mask, cidr: cidr)
+
+      if ending_address
+        startip = IPAddr.new starting_address.split('/').first
+        endip = IPAddr.new ending_address.to_s
+        validate_ip_range(startip, endip)
+      else
+        raise ArgumentError, 'Must provide ending_address:, mask:, cidr: or a masked starting_address:' unless starting_address.include? '/'
+        subnet = IPAddr.new starting_address
+        startip = subnet.to_range.first.mask 32
+        endip = subnet.to_range.last.mask 32
+      end
+
+      startip..endip
+    end
+
+    ### If we are given a mask or cidr, append them to the starting_address
+    ###
+    ### @param starting[String] The starting address, possibly masked
+    ###
+    ### @param mask[String] The subnet mask to apply to the starting address to get
+    ###   the ending address
+    ###
+    ### @param cidr[String, Integer] he cidr value to apply to the starting address to get
+    ###   the ending address
+    ###
+    ### @return [String] the starting with the mask or cidr appended
+    ###
+    def self.masked_starting_address(starting_address: nil, mask: nil, cidr: nil)
+      starting_address = "#{starting}/#{mask || cidr}" if mask || cidr
+      starting_address.to_s
+    end
+
+    ### Raise an exception if a given starting ip is higher than a given ending ip
+    ###
+    ### @param startip[String] The starting ip
+    ###
+    ### @param endip[String] The ending ip
+    ###
+    ### @return [void]
+    ###
+    def self.validate_ip_range(startip, endip)
+      return nil if IPAddr.new(startip.to_s) <= IPAddr.new(endip.to_s)
+      raise JSS::InvalidDataError, "Starting IP #{startip} is higher than ending ip #{endip} "
+    end
+
     ### Find the ids of the network segments that contain a given IP address.
     ###
     ### Even tho IPAddr.include? will take a String or an IPAddr
@@ -112,38 +188,38 @@ module JSS
     ###
     ### @return [Array<Integer>] the ids of the NetworkSegments containing the given ip
     ###
-    def self.network_segment_for_ip(ip)
+    def self.network_segments_for_ip(ip)
       ok_ip = IPAddr.new(ip)
       matches = []
-      self.network_ranges.each{ |id, subnet| matches << id if subnet.include?(ok_ip) }
+      network_ranges.each { |id, subnet| matches << id if subnet.include?(ok_ip) }
       matches
     end
 
-    ###
+    def self.network_segment_for_ip(ip)
+      network_segments_for_ip(ip)
+    end
+
     ### Find the current network segment ids for the machine running this code
     ###
     ### @return [Array<Integer>]  the NetworkSegment ids for this machine right now.
     ###
-    def self.my_network_segment
+    def self.my_network_segments
       network_segment_for_ip JSS::Client.my_ip_address
     end
 
+    def self.my_network_segment
+      my_network_segments
+    end
 
-
-    #####################################
     ### Attributes
     #####################################
 
-
     ### @return [IPAddr] starting IP adresss
     attr_reader :starting_address
 
     ### @return [IPAddr] ending IP adresss
     attr_reader :ending_address
 
-    ### @return [Integer] the CIDR
-    attr_reader :cidr
-
     ### @return [String] building for this segment. Must be one of the buildings in the JSS
     attr_reader :building
 
@@ -168,108 +244,127 @@ module JSS
     ### @return [Boolean] should machines checking in from this segment update their building
     attr_reader :override_buildings
 
-    ### @return [String] the unique identifier for this subnet, regardless of the JSS id
-    attr_reader :uid
-
-    ### @return [IPAddr] the IPAddr object representing this network segment, created from the uid
-    attr_reader :subnet
-
+    ### Instantiate a NetworkSegment
     ###
-    ### @see APIObject#initialize
+    ### @see_also JSS::NetworkSegment.ip_range for how starting and ending
+    ### addresses can be provided when using id: :new
     ###
-    def initialize(args = {} )
-
+    def initialize(args = {})
       super args
 
       if args[:id] == :new
-        raise MissingDataError, "Missing :starting_address." unless args[:starting_address]
-        raise MissingDataError, "Missing :ending_address or :cidr." unless args[:ending_address] or args[:cidr]
-        @init_data[:starting_address] = args[:starting_address]
-        @init_data[:ending_address] = args[:ending_address]
-        @init_data[:cidr] = args[:cidr].to_i
+        range = self.class.ip_range(
+          starting_address: args[:starting_address],
+          ending_address: args[:ending_address],
+          mask: args[:mask],
+          cidr: args[:cidr]
+        )
+        @init_data[:starting_address] = range.begin.to_s
+        @init_data[:ending_address] = range.end.to_s
       end
 
+      @starting_address = IPAddr.new @init_data[:starting_address]
+      @ending_address = IPAddr.new @init_data[:ending_address]
+
       @building = @init_data[:building]
       @department = @init_data[:department]
       @distribution_point = @init_data[:distribution_point]
       @netboot_server = @init_data[:netboot_server]
       @override_buildings = @init_data[:override_buildings]
       @override_departments = @init_data[:override_departments]
-      @starting_address = IPAddr.new @init_data[:starting_address]
       @swu_server = @init_data[:swu_server]
       @url = @init_data[:url]
+    end # init
 
-      ### by now, we must have either an ending address or a cidr
-      ### along with a starting address, so figure out the other one.
-      if @init_data[:ending_address]
-        @ending_address = IPAddr.new @init_data[:ending_address]
-        @cidr = IPAddr.jss_cidr_from_ends(@starting_address,@ending_address)
-      else
-        @cidr = @init_data[:cidr].to_i if @init_data[:cidr]
-        @ending_address = IPAddr.jss_ending_address(@starting_address, @cidr)
-      end # if args[:cidr]
-
-      ### we now have all our data, make our unique identifier, the startingaddr/cidr
-      @uid = "#{@starting_address}/#{@cidr}"
-
-      ### the IPAddr object for this whole net segment
-      @subnet = IPAddr.new @uid
-
-    end #init
+    ### a Range built from the start and end addresses.
+    ### To be used for finding inclusion and overlaps.
+    ###
+    ### @return [Range<IPAddr>] the range of IPAddrs for this segment.
+    ###
+    def range
+      @starting_address..@ending_address
+    end
 
+    ### Does this network segment overlap with another?
     ###
-    ### Thanks to Comparable, we can tell if we're equal or not.
+    ### @param other_segment[JSS::NetworkSegment] the other segment to check
     ###
-    ### See Comparable#<=>
+    ### @return [Boolean] Does the other segment overlap this one?
+    ###
+    def overlap?(other_segment)
+      raise TypeError, 'Argument must be a JSS::NetworkSegment' unless \
+        other_segment.is_a? JSS::NetworkSegment
+      other_range = other_segment.range
+      range.include?(other_range.begin) || range.include?(other_range.end)
+    end
+
+    ### Does this network segment include an address or another segment?
+    ### Inclusion means the other is completely inside this one.
     ###
-    ### @return [-1,0,1] ar we less than, equal or greater than the other?
+    ### @param thing[JSS::NetworkSegment, String, IPAddr] the other thing to check
     ###
-    def <=> (other)
-      self.subnet <=> other.subnet
+    ### @return [Boolean] Does this segment include the other?
+    ###
+    def include?(thing)
+      if thing.is_a? JSS::NetworkSegment
+        @starting_address <= thing.range.begin && @ending_address >= thing.range.end
+      else
+        thing = IPAddr.new thing.to_s
+        range.include? thing
+      end
     end
 
+    ### Does this network segment equal another?
+    ### equality means the ranges are equal
+    ###
+    ### @param other_segment[JSS::NetworkSegment] the other segment to check
     ###
+    ### @return [Boolean] Does this segment include the other?
+    ###
+    def ==(other)
+      raise TypeError, 'Argument must be a JSS::NetworkSegment' unless \
+        other.is_a? JSS::NetworkSegment
+      range == other.range
+    end
+
     ### Set the building
     ###
     ### @param newval[String, Integer] the new building by name or id, must be in the JSS
     ###
     ### @return [void]
     ###
-    def building= (newval)
-      new = JSS::Building.all.select{|b| b[:id] == newval or b[:name] == newval }[0]
+    def building=(newval)
+      new = JSS::Building.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
       raise JSS::MissingDataError, "No building matching '#{newval}'" unless new
       @building = new[:name]
       @need_to_update = true
     end
 
-    ###
     ### set the override buildings option
     ###
     ### @param newval[Boolean] the new override buildings option
     ###
     ### @return [void]
     ###
-    def override_buildings= (newval)
-      raise JSS::InvalidDataError, "New value must be boolean true or false" unless JSS::TRUE_FALSE.include? newval
+    def override_buildings=(newval)
+      raise JSS::InvalidDataError, 'New value must be boolean true or false' unless JSS::TRUE_FALSE.include? newval
       @override_buildings = newval
       @need_to_update = true
     end
 
-    ###
     ### set the department
     ###
     ### @param newval[String, Integer] the new dept by name or id, must be in the JSS
     ###
     ### @return [void]
     ###
-    def department= (newval)
-      new = JSS::Department.all.select{|b| b[:id] == newval or b[:name] == newval }[0]
+    def department=(newval)
+      new = JSS::Department.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
       raise JSS::MissingDataError, "No department matching '#{newval}' in the JSS" unless new
       @department = new[:name]
       @need_to_update = true
     end
 
-    ###
     ### set the override depts option
     ###
     ### @param newval[Boolean] the new setting
@@ -277,139 +372,145 @@ module JSS
     ### @return [void]
     ###
     ###
-    def override_departments= (newval)
-      raise JSS::InvalidDataError, "New value must be boolean true or false" unless JSS::TRUE_FALSE.include? newval
+    def override_departments=(newval)
+      raise JSS::InvalidDataError, 'New value must be boolean true or false' unless JSS::TRUE_FALSE.include? newval
       @override_departments = newval
       @need_to_update = true
     end
 
-    ###
     ### set the distribution_point
     ###
     ### @param newval[String, Integer] the new dist. point by name or id, must be in the JSS
     ###
     ### @return [void]
     ###
-    def distribution_point= (newval)
-      new = JSS::DistributionPoint.all.select{|b| b[:id] == newval or b[:name] == newval }[0]
+    def distribution_point=(newval)
+      new = JSS::DistributionPoint.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
       raise JSS::MissingDataError, "No distribution_point matching '#{newval}' in the JSS" unless new
       @distribution_point = new[:name]
       @need_to_update = true
     end
 
-    ###
     ### set the netboot_server
     ###
     ### @param newval[String, Integer] the new netboot server by name or id, must be in the JSS
     ###
     ### @return [void]
     ###
-    def netboot_server= (newval)
-      new = JSS::NetbootServer.all.select{|b| b[:id] == newval or b[:name] == newval }[0]
+    def netboot_server=(newval)
+      new = JSS::NetbootServer.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
       raise JSS::MissingDataError, "No netboot_server matching '#{newval}' in the JSS" unless new
       @netboot_server = new[:name]
       @need_to_update = true
     end
 
-    ###
     ### set the sw update server
     ###
     ### @param newval[String, Integer] the new server by name or id, must be in the JSS
     ###
     ### @return [void]
     ###
-    def swu_server= (newval)
-      new = JSS::SoftwareUpdateServer.all.select{|b| b[:id] == newval or b[:name] == newval }[0]
+    def swu_server=(newval)
+      new = JSS::SoftwareUpdateServer.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
       raise JSS::MissingDataError, "No swu_server matching '#{newval}' in the JSS" unless new
       @swu_server = new[:name]
       @need_to_update = true
     end
 
-    ###
     ### set the starting address
     ###
     ### @param newval[String, IPAddr] the new starting address
     ###
     ### @return [void]
     ###
-    def starting_address= (newval)
-      @starting_address = IPAddr.new newval # this will raise an error if the IP addr isn't valid
-      raise JSS::InvalidDataError, "New starting address #{@starting_address} is higher than ending address #{@ending_address}" if @starting_address > @ending_address
-      @cidr = IPAddr.jss_cidr_from_ends(@starting_address ,@ending_address)
-      @uid = "#{@starting_address}/#{@cidr}"
-      @subnet = IPAddr.new @uid
+    def starting_address=(newval)
+      self.class.validate_ip_range(newval, @ending_address)
+      @starting_address = IPAddr.new newval.to_s
       @need_to_update = true
     end
 
-    ###
     ### set the ending address
     ###
     ### @param newval[String, IPAddr] the new ending address
     ###
     ### @return [void]
     ###
-    def ending_address= (newval)
-      @ending_address = IPAddr.new newval # this will raise an error if the IP addr isn't valid
-      raise JSS::InvalidDataError, "New ending address #{@ending_address} is lower than starting address #{@starting_address}" if @ending_address < @starting_address
-      @cidr = IPAddr.jss_cidr_from_ends(@starting_address,@ending_address)
-      @uid = "#{@starting_address}/#{@cidr}"
-      @subnet = IPAddr.new @uid
+    def ending_address=(newval)
+      self.class.validate_ip_range(@starting_address, newval)
+      @ending_address = IPAddr.new newval.to_s
       @need_to_update = true
     end
 
+    ### set the ending address by applying a new cidr (e.g. 24)
+    ### or mask (e.g. 255.255.255.0)
     ###
-    ### set the cidr
-    ###
-    ### @param newval[String, IPAddr] the new cidr
+    ### @param newval[String, Integer] the new cidr or mask
     ###
     ### @return [void]
     ###
-    def cidr= (newval)
-      @cidr = newval
-      @ending_address = IPAddr.jss_ending_address(@starting_address, @cidr)
-      @uid = "#{@starting_address}/#{@cidr}"
-      @subnet = IPAddr.new @uid
+    def cidr=(newval)
+      new_end = IPAddr.new("#{@starting_address}/#{newval}").to_range.end.mask 32
+      self.class.validate_ip_range(@starting_address, new_end)
+      @ending_address = new_end
       @need_to_update = true
     end
 
+    ### set a new starting and ending addr at the same time.
+    ###
+    ### @see_also NetworkSegment.ip_range for how to specify the starting
+    ### and ending addresses.
+    ###
+    ### @param starting_address[String] The starting address, possibly masked
     ###
-    ### is a given address in this network segment?
+    ### @param ending_address[String] The ending address
     ###
-    ### @param some_addr[IPAddr,String] the IP address to check
+    ### @param mask[String] The subnet mask to apply to the starting address to get
+    ###   the ending address
     ###
-    ### @return [Boolean]
+    ### @param cidr[String, Integer] he cidr value to apply to the starting address to get
+    ###   the ending address
     ###
-    def include? (some_addr)
-      @subnet.include?  IPAddr.new(some_addr)
+    ### @return [void]
+    ###
+    def set_ip_range(starting_address: nil, ending_address: nil, mask: nil, cidr: nil)
+      range = self.class.ip_range(
+        starting_address: starting_address,
+        ending_address: ending_address,
+        mask: mask,
+        cidr: cidr
+      )
+      @starting_address = range.first
+      @ending_address = range.last
+      @need_to_update = true
     end
 
-
     ### aliases
-    alias identifier uid
-    alias range subnet
-
     ######################
+    alias mask= cidr=
+    alias to_range range
+
     ### private methods
+    ######################
     private
 
-    ###
     ### the xml formated data for adding or updating this in the JSS
     ###
     def rest_xml
       doc = REXML::Document.new APIConnection::XML_HEADER
-      ns = doc.add_element "network_segment"
+      ns = doc.add_element 'network_segment'
       ns.add_element('building').text = @building
       ns.add_element('department').text = @department
       ns.add_element('distribution_point').text = @distribution_point
-      ns.add_element('ending_address').text = @ending_address
+      ns.add_element('ending_address').text = @ending_address.to_s
       ns.add_element('name').text = @name
       ns.add_element('netboot_server').text = @netboot_server
       ns.add_element('override_buildings').text = @override_buildings
       ns.add_element('override_departments').text = @override_departments
-      ns.add_element('starting_address').text = @starting_address
+      ns.add_element('starting_address').text = @starting_address.to_s
       ns.add_element('swu_server').text = @swu_server
-      return doc.to_s
-    end #rest_xml
+      doc.to_s
+    end # rest_xml
 
   end # class NetworkSegment
+
 end # module