.. _configure-PBR-add-on:

Configure Phone Based Registration
-----------------------------------

.. index:: app;app start phone-based-registration


The Phone Based Registration (PBR) feature supports a number of configuration parameters
that manage how the service operates in a specific provider or customer environment.
This configuration is implemented using the **Services > Phone Based Registration > PBR Config**
menu item.

* A single PBR config record MUST be created globally at provider level.
* A PBR config record must be created for each customer that will utilize the phone
  based registration add-on.
* The config at the provider level is there to enable the PBR web service to make
  initial connection to VOSS Automate API.
* The config at customer level defines the specific connection parameters for that
  customer and eventually will allow per customer VOSS Automate user to be used.

|PBR-config-list.png|

Configuration is on VOSS Automate user interface:

|PBR-config-detail.png|

Figure 5: Sample PBR Config record

When configuring the PBR service for a specific hierarchy the following
considerations are important:

1. VOSS recommends that PBR configuration should only allow the replacement of
   phones with fake MACs with device name prefix starting with BAT.

   This ensures that it is never possible for a user to replace a phone that is in active use.
   
   Select the **BAT Prefix Required** check box.

2. Is the use of PBR Device records required in this environment?

   a. The PBR device record provides a mechanism for administrators to explicitly
      specify that a device is eligible for phone based registration.

      Select the **PBR Device Record Required** check box if this is desired.

   b. The PBR device record allows the administrator to specify a PIN that should
      be used when performing phone based registration for a specific phone or for
      all phones at a site.

      Select the **Pin Required** check box.

   c. The PBR device record can be used to guarantee that the correct device is
      replaced in environments where Directory numbers are not unique within a
      Unified CM cluster, e.g. multiple Directory numbers are configured with same DN
      but located in different partitions.

      In this case, clear the **UseSiteWidePIN** check box.

Phone Registration Portal Port:

* This should be port 443 for HTTPS based connectivity
* This can be port 80 for HTTP based connectivity

Phone Registration Portal Address:

* When using HTTPS, this is the IP address or hostname of a VOSS Automate proxy node
  in a cluster.
* When using HTTP, this is the IP address or hostname of the primary VOSS Automate
  unified node in a cluster.
* This address and the port below must be accessible from the phone network.

Phone Registration Portal API User Credentials:

* Phone Registration Portal API User:

  * This is the user that was configured in the previous section of documentation.
    Please specify the email address.
    
* Phone Registration Portal API Password:

  * The password of the PBR API user:

  Note that this information is required for both the Provider level config and
  the config for any customers.

Phone Registration Service Hierarchy:

* If the config record is defined at Provider level, then this should be the
  Provider hierarchy, e.g. sys.hcs.CC-P.
* If the config record is defined at the customer level, then this should be the
  customer hierarchy, e.g. sys.hcs.CC-P.FlexCorp)

CUCM IP:

* This should be the IP address of Unified CM that is accessible to VOSS Automate using
  HTTPS SOAP requests.

By default, VOSS Automate requires a PBR device record per device, but in some cases,
it could be sufficient to use a single pin per site:

1. In this case, select the **UseSiteWidePIN** check box.
2. This provides limited security to ensure that a PIN is still required to register
   a phone, but reduces the operational burden by eliminating the need to provision
   a PBR device record for each phone.

Additional options:

* Auto Provision PBR device record. This feature is experimental and should **not
  be selected**.
* Use default PIN. This feature is experimental and should **not be selected**.
* BAT devicename format: This should be left to default.


.. Important::

   After saving the above configuration in VOSS Automate, you must restart the services
   by running the following CLI command on the primary node:
   
   **cluster run all app start phone-based-registration**


.. rubric:: Related Topics

* :ref:`intro-PBR`



.. |PBR-config-list.png| image:: /src/images/PBR-config-list.png
.. |PBR-config-detail.png| image:: /src/images/PBR-config-detail.png