Promiscuous Access for Devices
This section describes the objects and the properties that are used to control the configuration of devices that are granted promiscuous access.
Devices are said to be given promiscuous access if they are allowed to boot and be configured without being preregistered in Prime Cable Provisioning. Promiscuous access is typically used for devices, such as computers, that appear behind a DOCSIS modem. If promiscuous access is not enabled for unknown devices behind a DOCSIS modem, the devices receive the default service level.
To grant promiscuous access to a device, you must:
-
Enable or disable the promiscuous policy for unknown devices of a given type. Devices for which promiscuous access is enabled are configured according to the policy, instead of receiving the default configuration.
-
Specify the Class of Service meant for unknown devices of a given type if the devices are to be given promiscuous access.
-
Specify the DHCP Criteria meant for unknown devices of a given type if the devices are to be given promiscuous access.
Note |
Prior to Prime Cable Provisioning 6.3 release, promiscuous access can be enabled for devices behind a registered DOCSIS modem only, from Prime Cable Provisioning 6.3, promiscuous access can be enabled for devices behind unregistered DOCSIS modem by enabling the property available in System Defaults page or Table 1. |
Configuring Promiscuous Access
The following table describes the ways in which you can configure a promiscuous policy for a device. The Provisioning group and Technology-specific promiscuous mode configuration are not possible through the Admin UI.
Configuration Scope |
Using API Calls... |
|
---|---|---|
Provisioning group of Cable Modem—For example, you can configure promiscuous access to allow computers only behind any Cable Modem device in a specific provisioning group. |
getProvGroupDetails changeProvGroupProperties |
|
Class of Service object of Cable Modem—For example, you can configure promiscuous access to allow computers only behind DOCSIS modems that are associated with a specific Class of Service. |
addClassOfService changeClassOfServiceProperties getClassOfServiceProperties |
|
DHCP Criteria of Cable Modem—For example, you can configure promiscuous access to allow computers only behind DOCSIS modems that are associated with a specific DHCP Criteria. |
addDHCPCriteria changeDHCPCriteriaProperties getDHCPCriteriaDetails |
|
Technology-specific defaults—For example, you can configure promiscuous access for computers behind DOCSIS modems using the technology defaults for DOCSIS modems. |
changeDefaults getDefaults |
|
System-wide defaults—Global system defaults |
changeSystemDefaults getSystemDefaults |
Promiscuous Access and Property Hierarchy
You can configure a promiscuous policy on a number of objects in Prime Cable Provisioning. It is, therefore, important to understand the settings that take precedence. While the policy is configured using properties, the precedence of properties is determined by the Prime Cable Provisioning property hierarchy. The first object in the property hierarchy that has a specific property determines the value that Prime Cable Provisioning is to use.
Prime Cable Provisioning looks up the properties of the promiscuous policy in the property hierarchy of the device’s Cable Modem. For example, for a computer, Prime Cable Provisioning looks up the promiscuous policy settings in the property hierarchy of the cable modem, which functions as a relay for the computer. For more details about property hierarchy, see Property Hierarchy. For more details about promiscuous policy see Properties for Configuring Promiscuous Policy.
Note |
When you set the promiscuous policy using technology defaults, the properties must be set on objects associated with the Cable Modem, not the target device type. For example, to enable promiscuous access for computers behind a DOCSIS modem, you can enable promiscuous access on technology defaults for the DOCSIS modem, but not on technology defaults for computers. |
The promiscuous policy properties specify the Class of Service, the DHCP Criteria, and whether promiscuous access is enabled or disabled for each device type. If promiscuous mode is enabled for a device, but a search of the device’s Cable Modem hierarchy does not locate a match of the Class of Service or DHCP Criteria properties, the default Class of Service or DHCP Criteria for non-promiscuous access are used. For example, if Prime Cable Provisioning is configured to grant promiscuous access to computers, but it cannot locate a promiscuous Class of Service, DHCP Criteria, or both, then it uses the default Class of Service, DHCP Criteria, or both for the computer.
The Class of Service and the DHCP Criteria defaults are configured on the technology defaults of the target device (instead of its Cable Modem) using these properties:
-
Class of Service—/default/classOfService
The API constant is
TechnologyDefaultsKeys.DEFAULT_CLASS_OF_SERVICE.
-
DHCP Criteria—/default/dhcpCriteria
The API constant is
TechnologyDefaultsKeys.DEFAULT_DHCP_CRITERIA.
Generating Configurations for Promiscuous Devices
The configuration for promiscuous devices is generated under these conditions:
-
The device first appears online and is given promiscuous access.
-
An out-of-date DPE is populating its cache and requests configurations for a specific provisioning group.
-
Regeneration of the configuration is explicitly requested for the device via the API call regenConfigs.
-
Configuration of the Cable Modem device for a promiscuous access device is being regenerated.
-
Changes to the promiscuous policy (or other configuration changes) prompt the Prime Cable Provisioning Configuration Regeneration Service (CRS) service to regenerate configurations of affected devices.
Every time a configuration for a promiscuous device is regenerated, it uses the newly configured promiscuous policy (for example, the Class of Service currently specified for promiscuous computers). However, if the Class of Service or DHCP Criteria of a device is changed via the API after the device appears online as a promiscuous device, then from then on, the device is not considered promiscuous and is unaffected by any changes that you make to the promiscuous policy. The device is henceforth considered registered.
Properties for Configuring Promiscuous Policy
To configure promiscuous access for devices, you must configure the properties associated with specific device types that Prime Cable Provisioning supports. You can enable or disable promiscuous access for the device types.
-
Enabled—Enables promiscuous access for devices within the scope associated with the API call that Table 1 describes.
-
Disabled—Disables promiscuous access. If the property does not exist, the default is the disabled setting.
See Table 1 for a list of properties on which you configure promiscuous access.
Promiscuous policy properties are divided into read-write and read-only properties. This section describes the read-write and read-only properties that you must configure to enable promiscuous access for devices and those that you set to select Class of Service or DHCP Criteria for these devices.
Read-Write Properties
Note |
Table 1 describes the applicable API calls for all the properties that are described in this section. |
Table 1 describes the properties that you can use to enable promiscuous access.
Property Name |
Description |
---|---|
/promiscuousMode/enable/Computer |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for computers behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuousMode/enable/ PacketCableMTA |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for PacketCable MTAs behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuousMode/enable/STB |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for STBs behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuous/enable/unregisteredCM |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
|
API Constant
|
|
/promiscuousMode/enable/ CableHomeWanData |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for WAN-Data devices behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuousMode/enable/ CableHomeWanMan |
Sets a Boolean value of “true” or “false” in the Cable Modem's property hierarchy:
If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for WAN-MAN devices behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuousMode/enable/ERouter | Sets a Boolean value of
“true” or “false” in the Cable Modem's property hierarchy:
• true—Enables promiscuous access for eRouters behind such a relay. • false—Disables promiscuous access for eRouters behind such a relay. If the property does not exist in the Cable Modem's property hierarchy, promiscuous access for eRouters behind such a relay is disallowed and the devices receive default access. |
API Constant
|
|
/promiscuousMode/enable/ |
Use this property to enable or disable promiscuous access for new types of devices by appending the property name with the name of a valid device type. Sets a Boolean value of “true” or “false.” |
API Constant
|
The following table describes the read-write properties that you must configure to select Class of Service for devices granted promiscuous access.
Class of Service Property Name |
Description |
|
---|---|---|
/provisioning/cpeClassOfService/ Computer |
Specifies the name of an existing Class of Service that will be selected for promiscuous computers |
|
API Constant
|
||
/provisioning/cpeClassOfService/ PacketCableMTA |
Specifies the name of an existing Class of Service that will be selected for promiscuous PacketCable MTAs |
|
API Constant
|
||
/provisioning/cpeClassOfService/ STB |
Specifies the name of an existing Class of Service that will be selected for promiscuous set-top boxes |
|
API Constant
|
||
/provisioning/cpeClassOfService/ CableHomeWanMan |
Specifies the name of an existing Class of Service that will be selected for promiscuous CableHome WAN-Data devices |
|
API Constant
|
||
/provisioning/cpeClassOfService/ CableHomeWanData |
Specifies the name of an existing Class of Service that will be selected for promiscuous CableHome WAN-MAN devices |
|
API Constant
|
||
/provisioning/cpeClassOfService/ERouter | Specifies the name of an existing Class of Service that will be selected for promiscuous eRouters | |
API Constant
|
||
/provisioning/cpeClassOfService/ |
Specifies an existing Class of Service that will be selected for devices of the specified device type. Use this property name with a valid device type name. You can use this property for custom device types. |
|
API Constant
|
The following table describes the read-write properties that you must configure to select DHCP Criteria for devices granted promiscuous access.
DHCP Criteria Property Name |
Description |
|
---|---|---|
/provisioning/cpeDhcpCriteria/ Computer |
Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous computers |
|
API Constant
|
||
/provisioning/cpeDhcpCriteria/ PacketCableMTA |
Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous PacketCable MTAs |
|
API Constant
|
||
/provisioning/cpeDhcpCriteria/STB |
Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous set-top boxes |
|
API Constant
|
||
/provisioning/cpeDhcpCriteria/ CableHomeWanData |
Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous CableHome WAN-Data devices |
|
API Constant
|
||
/provisioning/cpeDhcpCriteria/ CableHomeWanMan |
Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous CableHome WAN-MAN devices |
|
API Constant
|
||
/provisioning/cpeDhcpCriteria/ERouter | Specifies the name of an existing DHCP Criteria object that will be selected for promiscuous eRouters | |
API Constant
|
||
/provisioning/cpeDhcpCriteria/ |
Specifies an existing DHCP Criteria object that will be selected for devices of the specified device type. Use this property name with a valid device type name. You can use this property for custom device types. |
|
API Constant
|
Read-Only Properties
The following table covers read-only promiscuous properties that you must configure to select the Class of Service and the DHCP Criteria for devices. Together with the read-write properties specified in the previous section, these read-only properties help determine the current system configuration.
Property Name |
Description |
|||
---|---|---|---|---|
/isSystemWide/default/promiscuous |
Returns a “true” value if a given Class Of Service or DHCP Criteria object is referenced as system-wide default for promiscuous devices. |
|||
Applicable API Calls getClassOfServiceProperties getDHCPCriteriaDetails |
API Constant
|
|||
/referencedBy/deviceTypes/ forPromiscuousDevices |
Returns a list of Device Type object (technology) names that reference a given Class of Service or DHCP Criteria object in promiscuous policy properties |
|||
Applicable API Calls getClassOfServiceProperties getDHCPCriteriaDetails |
API Constant
|
|||
/related/classesOfService |
Returns a list of Class of Service object names that are used by a given Class of Service or DHCP Criteria object in promiscuous policy properties
|
|||
Applicable API Calls getClassOfServiceProperties getDHCPCriteriaDetails |
API Constant
|
|||
/related/dhcpCriteria |
Returns a list of DHCP Criteria object names that are used by a given Class of Service or DHCP Criteria object in promiscuous policy properties
|
|||
Applicable API Calls getClassOfServiceProperties getDHCPCriteriaDetails |
API Constant
|
Custom Policy for Promiscuous Devices
You can configure promiscuous policy for a device using the properties specified in the above section. When additional logic is required, however, you can implement custom logic using extensions and custom properties. Custom properties allow for the definition of new properties, which can then be stored on any object via the API.
To augment the promiscuous device policy, you can use these extensions:
-
Device Detection—Determines the technology type of the device (usually based on DHCP request data). Information that this extension detects is placed in a Device Detection Context that other extensions then use.
-
Service-Level Selection—Selects the appropriate Class of Service and DHCP Criteria objects for a device. The promiscuous policy properties determine the Class of Service and DHCP Criteria for devices with promiscuous access.
-
Configuration Generation—Generates the configuration for a device and, if necessary, for the devices behind it. Configurations are regenerated for promiscuous devices behind the Cable Modem based on the policy that the service-level selection extension selects. You may need to change the extension only if you want to augment the default behavior of regenerating configuration for devices behind a Cable Modem.