Class: JSS::NetworkSegment

Inherits:
APIObject show all
Includes:
Comparable, Creatable, Updatable
Defined in:
lib/jss/api_object/network_segment.rb,
lib/jss.rb

Overview

A Network Segment in the JSS

Constant Summary collapse

RSRC_BASE =

the REST resource base

'networksegments'.freeze
RSRC_LIST_KEY =

the hash key used for the JSON list output of all objects in the JSS

:network_segments
RSRC_OBJECT_KEY =

The hash key used for the JSON object output. It’s also used in various error messages

:network_segment
VALID_DATA_KEYS =

these keys, as well as :id and :name, are present in valid API JSON data for this class

[:distribution_point, :starting_address, :override_departments].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ NetworkSegment

Instantiate a NetworkSegment

addresses can be provided when using id: :new



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/jss/api_object/network_segment.rb', line 252

def initialize(args = {})
  super args

  if args[:id] == :new
    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]
  @swu_server = @init_data[:swu_server]
  @url = @init_data[:url]
end

Instance Attribute Details

#building ⇒ String

Returns building for this segment. Must be one of the buildings in the JSS.

Returns:

  • (String) —

    building for this segment. Must be one of the buildings in the JSS



224
225
226
 
# File 'lib/jss/api_object/network_segment.rb', line 224

def building
  @building
end

#department ⇒ String

Returns department for this segment. Must be one of the depts in the JSS.

Returns:

  • (String) —

    department for this segment. Must be one of the depts in the JSS



227
228
229
 
# File 'lib/jss/api_object/network_segment.rb', line 227

def department
  @department
end

#distribution_point ⇒ String

Returns the name of the distribution point to be used from this network segment.

Returns:

  • (String) —

    the name of the distribution point to be used from this network segment



230
231
232
 
# File 'lib/jss/api_object/network_segment.rb', line 230

def distribution_point
  @distribution_point
end

#ending_address ⇒ IPAddr

Returns ending IP adresss.

Returns:

  • (IPAddr) —

    ending IP adresss



221
222
223
 
# File 'lib/jss/api_object/network_segment.rb', line 221

def ending_address
  @ending_address
end

#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    do we have unsaved changes?

#netboot_server ⇒ String

Returns the netboot server for this segment.

Returns:

  • (String) —

    the netboot server for this segment



236
237
238
 
# File 'lib/jss/api_object/network_segment.rb', line 236

def netboot_server
  @netboot_server
end

#override_buildings ⇒ Boolean

Returns should machines checking in from this segment update their building.

Returns:

  • (Boolean) —

    should machines checking in from this segment update their building



245
246
247
 
# File 'lib/jss/api_object/network_segment.rb', line 245

def override_buildings
  @override_buildings
end

#override_departments ⇒ Boolean

Returns should machines checking in from this segment update their dept.

Returns:

  • (Boolean) —

    should machines checking in from this segment update their dept



242
243
244
 
# File 'lib/jss/api_object/network_segment.rb', line 242

def override_departments
  @override_departments
end

#starting_address ⇒ IPAddr

Returns starting IP adresss.

Returns:

  • (IPAddr) —

    starting IP adresss



218
219
220
 
# File 'lib/jss/api_object/network_segment.rb', line 218

def starting_address
  @starting_address
end

#swu_server ⇒ String

Returns the swupdate server for this segment.

Returns:

  • (String) —

    the swupdate server for this segment.



239
240
241
 
# File 'lib/jss/api_object/network_segment.rb', line 239

def swu_server
  @swu_server
end

#url ⇒ String (readonly)

Returns the mount url for the distribution point.

Returns:

  • (String) —

    the mount url for the distribution point



233
234
235
 
# File 'lib/jss/api_object/network_segment.rb', line 233

def url
  @url
end

Class Method Details

.ip_range(starting_address: nil, ending_address: nil, mask: nil, cidr: nil) ⇒ Range<IPAddr>

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.

Parameters:

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

    The starting address, possibly masked

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

    The ending address. If given, it overrides mask:, cidr: and a masked starting_address:

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

    The subnet mask to apply to the starting address to get the ending address

  • cidr (String, Integer) (defaults to: nil) —

    he cidr value to apply to the starting address to get the ending address

Returns:

  • (Range<IPAddr>) —

    the valid Range

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/jss/api_object/network_segment.rb', line 132

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

.masked_starting_address(starting_address: nil, mask: nil, cidr: nil) ⇒ String

If we are given a mask or cidr, append them to the starting_address

Parameters:

  • starting (String) —

    The starting address, possibly masked

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

    The subnet mask to apply to the starting address to get the ending address

  • cidr (String, Integer) (defaults to: nil) —

    he cidr value to apply to the starting address to get the ending address

Returns:

  • (String) —

    the starting with the mask or cidr appended



163
164
165
166
 
# File 'lib/jss/api_object/network_segment.rb', line 163

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

.my_network_segment ⇒ Object 



210
211
212
 
# File 'lib/jss/api_object/network_segment.rb', line 210

def self.my_network_segment
  my_network_segments
end

.my_network_segments ⇒ Array<Integer>

Find the current network segment ids for the machine running this code

Returns:

  • (Array<Integer>) —

    the NetworkSegment ids for this machine right now.



206
207
208
 
# File 'lib/jss/api_object/network_segment.rb', line 206

def self.my_network_segments
  network_segment_for_ip JSS::Client.my_ip_address
end

.network_ranges(refresh = false) ⇒ Hash{Integer => Range}

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>

Using the #include? method on those Ranges is very useful.

Returns:

  • (Hash{Integer => Range}) —

    the network segments as IPv4 address Ranges



77
78
79
80
81
82
83
 
# File 'lib/jss/api_object/network_segment.rb', line 77

def self.network_ranges(refresh = false)
  @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

.network_segment_for_ip(ip) ⇒ Object 



198
199
200
 
# File 'lib/jss/api_object/network_segment.rb', line 198

def self.network_segment_for_ip(ip)
  network_segments_for_ip(ip)
end

.network_segments_for_ip(ip) ⇒ Array<Integer>

Find the ids of the network segments that contain a given IP address.

Even tho IPAddr.include? will take a String or an IPAddr I convert the ip to an IPAddr so that an exception will be raised if the ip isn’t a valid ip.

Parameters:

Returns:

  • (Array<Integer>) —

    the ids of the NetworkSegments containing the given ip



191
192
193
194
195
196
 
# File 'lib/jss/api_object/network_segment.rb', line 191

def self.network_segments_for_ip(ip)
  ok_ip = IPAddr.new(ip)
  matches = []
  network_ranges.each { |id, subnet| matches << id if subnet.include?(ok_ip) }
  matches
end

.subnets(refresh = false) ⇒ Object

An alias for network_ranges

DEPRECATED: This will be going away in a future release.

See Also:

  • {NetworkSegment{NetworkSegment::network_ranges}


91
92
93
 
# File 'lib/jss/api_object/network_segment.rb', line 91

def self.subnets(refresh = false)
  network_ranges refresh
end

.validate_ip_range(startip, endip) ⇒ void

This method returns an undefined value.

Raise an exception if a given starting ip is higher than a given ending ip

Parameters:

  • startip (String) —

    The starting ip

  • endip (String) —

    The ending ip

Raises:



176
177
178
179
 
# File 'lib/jss/api_object/network_segment.rb', line 176

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

Instance Method Details

#==(other) ⇒ Boolean

Does this network segment equal another? equality means the ranges are equal

Parameters:

Returns:

  • (Boolean) —

    Does this segment include the other?

Raises:

  • (TypeError) 


324
325
326
327
328
 
# File 'lib/jss/api_object/network_segment.rb', line 324

def ==(other)
  raise TypeError, 'Argument must be a JSS::NetworkSegment' unless \
    other.is_a? JSS::NetworkSegment
  range == other.range
end

#cidr=(newval) ⇒ void Also known as: mask=

This method returns an undefined value.

set the ending address by applying a new cidr (e.g. 24) or mask (e.g. 255.255.255.0)

Parameters:

  • newval (String, Integer) —

    the new cidr or mask



451
452
453
454
455
456
 
# File 'lib/jss/api_object/network_segment.rb', line 451

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

#clone(new_name) ⇒ APIObject Originally defined in module Creatable

make a clone of this API object, with a new name. The class must be creatable

Parameters:

  • name (String) —

    the name for the new object

Returns:

  • (APIObject) —

    An uncreated clone of this APIObject with the given name

Raises:

#create ⇒ Integer Originally defined in module Creatable

Create a new object in the JSS.

Returns:

  • (Integer) —

    the jss ID of the newly created object

Raises:

#include?(thing) ⇒ Boolean

Does this network segment include an address or another segment? Inclusion means the other is completely inside this one.

Parameters:

Returns:

  • (Boolean) —

    Does this segment include the other?



308
309
310
311
312
313
314
315
 
# File 'lib/jss/api_object/network_segment.rb', line 308

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

#name=(newname) ⇒ void Originally defined in module Updatable

This method returns an undefined value.

Change the name of this item Remember to #update to push changes to the server.

Parameters:

  • newname (String) —

    the new name

Raises:

#overlap?(other_segment) ⇒ Boolean

Does this network segment overlap with another?

Parameters:

Returns:

  • (Boolean) —

    Does the other segment overlap this one?

Raises:

  • (TypeError) 


294
295
296
297
298
299
 
# File 'lib/jss/api_object/network_segment.rb', line 294

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

#range ⇒ Range<IPAddr> Also known as: to_range

a Range built from the start and end addresses. To be used for finding inclusion and overlaps.

Returns:

  • (Range<IPAddr>) —

    the range of IPAddrs for this segment.



284
285
286
 
# File 'lib/jss/api_object/network_segment.rb', line 284

def range
  @starting_address..@ending_address
end

#set_ip_range(starting_address: nil, ending_address: nil, mask: nil, cidr: nil) ⇒ void

This method returns an undefined value.

set a new starting and ending addr at the same time.

and ending addresses.

Parameters:

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

    The starting address, possibly masked

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

    The ending address

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

    The subnet mask to apply to the starting address to get the ending address

  • cidr (String, Integer) (defaults to: nil) —

    he cidr value to apply to the starting address to get the ending address



475
476
477
478
479
480
481
482
483
484
485
 
# File 'lib/jss/api_object/network_segment.rb', line 475

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

#update ⇒ Boolean Originally defined in module Updatable

Save changes to the JSS

Returns:

  • (Boolean) —

    success

Raises: