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
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry

43

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



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/jss/api_object/network_segment.rb', line 291

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



263
264
265
 
# File 'lib/jss/api_object/network_segment.rb', line 263

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



266
267
268
 
# File 'lib/jss/api_object/network_segment.rb', line 266

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



269
270
271
 
# File 'lib/jss/api_object/network_segment.rb', line 269

def distribution_point
  @distribution_point
end

#ending_address ⇒ IPAddr

Returns ending IP adresss.

Returns:

  • (IPAddr) —

    ending IP adresss



260
261
262
 
# File 'lib/jss/api_object/network_segment.rb', line 260

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



275
276
277
 
# File 'lib/jss/api_object/network_segment.rb', line 275

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



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

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



281
282
283
 
# File 'lib/jss/api_object/network_segment.rb', line 281

def override_departments
  @override_departments
end

#starting_address ⇒ IPAddr

Returns starting IP adresss.

Returns:

  • (IPAddr) —

    starting IP adresss



257
258
259
 
# File 'lib/jss/api_object/network_segment.rb', line 257

def starting_address
  @starting_address
end

#swu_server ⇒ String

Returns the swupdate server for this segment.

Returns:

  • (String) —

    the swupdate server for this segment.



278
279
280
 
# File 'lib/jss/api_object/network_segment.rb', line 278

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



272
273
274
 
# File 'lib/jss/api_object/network_segment.rb', line 272

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:



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

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



165
166
167
168
 
# File 'lib/jss/api_object/network_segment.rb', line 165

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(api: JSS.api) ⇒ Object

Deprecated.

use my_network_segments

Here for backward compatibility



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

def self.my_network_segment(api: JSS.api)
  my_network_segments api: api
end

.my_network_segments(refresh = false, names: false, api: JSS.api) ⇒ 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.



215
216
217
218
219
220
221
 
# File 'lib/jss/api_object/network_segment.rb', line 215

def self.my_network_segments(refresh = false, names: false, api: JSS.api)
  ids = network_segments_for_ip JSS::Client.my_ip_address, refresh, api: api
  return ids unless names

  ids_to_names = map_all_ids_to :name
  ids.map { |id| ids_to_names[id] }
end

.network_ranges(refresh = false, api: JSS.api) ⇒ Hash{Integer => Range}

All NetworkSegments in the given API 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.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    should the data be re-queried?

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    the API to query

Returns:

  • (Hash{Integer => Range}) —

    the network segments as IPv4 address Ranges keyed by id



83
84
85
 
# File 'lib/jss/api_object/network_segment.rb', line 83

def self.network_ranges(refresh = false, api: JSS.api)
  api.network_ranges refresh
end

.network_segment_for_ip(ip, api: JSS.api) ⇒ Object

Deprecated.

use network_segments_for_ip

Here for Backward compatibility



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

def self.network_segment_for_ip(ip, api: JSS.api)
  network_segments_for_ip(ip, api: api)
end

.network_segments_for_ip(ip, refresh = false, api: JSS.api) ⇒ 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:

  • ip (String, IPAddr) —

    the IP address to locate

  • refresh (Boolean) (defaults to: false) —

    should the data be re-queried?

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The API connection to query

Returns:

  • (Array<Integer>) —

    the ids of the NetworkSegments containing the given ip



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

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

.subnets(refresh = false, api: JSS.api) ⇒ Object

An alias for network_ranges

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

See Also:

  • {NetworkSegment{NetworkSegment::network_ranges}


93
94
95
 
# File 'lib/jss/api_object/network_segment.rb', line 93

def self.subnets(refresh = false, api: JSS.api)
  network_ranges refresh, api: api
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:



178
179
180
181
182
 
# File 'lib/jss/api_object/network_segment.rb', line 178

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) 


363
364
365
366
367
 
# File 'lib/jss/api_object/network_segment.rb', line 363

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



490
491
492
493
494
495
 
# File 'lib/jss/api_object/network_segment.rb', line 490

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, api: nil) ⇒ 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

  • api (JSS::APIConnection) (defaults to: nil) —

    the API in which to create the object Defaults to the API used to instantiate this 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.

Parameters:

  • api (JSS::APIConnection) —

    the API in which to create the object Defaults to the API used to instantiate this object

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?



347
348
349
350
351
352
353
354
 
# File 'lib/jss/api_object/network_segment.rb', line 347

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) 


333
334
335
336
337
338
 
# File 'lib/jss/api_object/network_segment.rb', line 333

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.



323
324
325
 
# File 'lib/jss/api_object/network_segment.rb', line 323

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



514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/jss/api_object/network_segment.rb', line 514

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: