Updated: September 15, 2020 9:49am

Prism DSC Enterprise

Prism DSC Enterprise leverages Microsoft's Desired State Configuration (DSC) technology to make it easier to bring/keep Prism server machines to a desired state. Using DSC, you can update Prism components on multiple nodes in the enterprise. With DSC, you don't have to configure machines manually. DSC puts a computer into a desired state of configuration and then keeps the computer in that desired state. If you change your mind about what a computer should look like, you modify its DSC configuration. DSC will read the new configuration and automatically update the configuration, bringing the computer in compliance with your new desired state.
DSC is meant for scale - when you need to manage dozens or even hundreds or servers. In this type of environment, you can simply assign the same configuration file to multiple nodes. This works well in situations where you want multiple nodes to be configured identically with a certain predetermined set of components.
DSC Components

  • Nodes: Nodes are the individual Prism installations managed by DSC. These can be regular Prism server installations, or a Proxy-only installation.
  • Profiles: Profiles enable users to define what products (Proxy, Server, etc.) are installed for each computer/node. Example profiles could be "Proxy-Only" for workstations or "Full-Stack" for the backend server.
  • Groups: Groups are used as an abstract way to group computers for updates. Users should add nodes to groups according to what versions or products and what profiles they would like to use on said group. A group could be called "Folsom" with the following nodes added to our new Folsom group: "WKS-Folsom-1" and "WKS-Folsom-2". Once this group is defined, you can set the profile for this group to define which Prism products should be updated/maintained. Once the group is set up and the profile is set, the user can select which version of prism they would like to apply to the said group. Once the group setup is complete, the user can click the Update button to update all nodes in the group with the selected prism version.

Sample DSC Topology
DSC topology

Prism DSC Limitations and Notes

  • The current version of DSC can only update machines that have an existing Prism installation; it cannot install and initialize a new Prism server
  • The current version of DSC can only update the Apache, Prism Server, Proxy and V9/DRS; it cannot update Doc Designer or Technician's Toolkit
  • Requires Windows Server 2012 R2 or Server 2016
  • Requires MS Powershell 5.1 or higher on each machine taking part in the deployment
  • The DSC server must have MS IIS (Internet Information Server; Web server) installed
  • The Retail Pro DSC Enterprise installer consists of a single executable (.exe)
  • The DSC Enterprise GUI runs in a web browser

DSC - Basic Steps

  1. Verify that the DSC Server and and all nodes taking part meet the system requirements.
  2. Install the DSC Server and verify DSC Server settings. Change individual settings as needed.
  3. Create groups. When creating a group, you specify the POA Server for the group.
  4. Using the Check Server button, check the nodes available for each group and import nodes.
  5. Verify that installable Prism releases are in the \DSC Enterprise\Installers directory.
  6. When it is time to upgrade, select the Prism version that will be used for the upgrade. Select the nodes to be upgraded.

Install DSC Server
DSC uses a client-server model. One machine in the enterprise will server as the DSC Server. The other individual Prism servers (nodes) will communicate with the server to receive instructions about which components to install. The DSC server is typically not part of the Prism enterprise (although it could be).

  1. Navigate to the RetailProDSCEnterpriseInstaller.exe file and double-click the file. The wizard will lead you through the installation.    
  2. When the installation is complete, the files will be in the C:\Program Files (x86)\Retail Pro DSC Enterprise folder.
  3. Launch PrismDSCEnterprise.exe
  4. Navigate to the root \Retail Pro DSC Enterprise folder.
  5. Double-click the RetailProDSCWebClient.exe file.

Verify DSC Server Settings

When you launch the DSC.exe, the home screen is displayed. Click the hamburger icon and select settings so you can verify the server settings and modify settings if needed. After installing the DSC server, go into the settings area and verify that the DSC Server settings are correct. The settings available in each section are explained on the pages that follow. Important! The Pull Server FQDN MUST have the correct domain extension as specified in the Common Name (CN) field of the certificate.
DSC Server Notes

  • Maintenance window awareness
  • The DSC Server must have the company's CodeSign certificate and the CA Cert RA certificates installed.
  • The DSC Server must have a Server SSL Certificate generated and installed indicating that the server is a trusted source. This certificate has to be installed on the server only.

Host Credential Management
The Host Credential Management section allows the user to manage the host credentials stored on the database. These are used for DSC replication. Click Verify to verify the stored host credentials are valid. Click Update to update the stored host credentials to entered values.

Pull Server Management
In this section, verify the location of the \Installers directory. Copy Prism installers to this folder.

Field    Description
Installation Directory    Location of where the prism installer packages will reside on the host machine for distribution.
Pull Server FQDN    The fully qualified domain name of the host machine. This must be the same FQDN that is validated by the pull server SSL certificate.

Default Maintenance Settings
Default Maintenance Settings: allow the user to set default values to be inherited when creating a new node that is not part of a group.  Maintenance window values control when an update can be applied to target machines. The installers will only run if the machine is in its current maintenance window.
DSC Staging Directory: The DSC staging directory is where target nodes will store local data including the installers to be run on the machine.
Time Zone: Default time zone
Maintenance Window Start Time: Default maintenance window start time
Maintenance Window Stop Time: Default maintenance window stop time

Certificate Management
PullServerCert: Public key of the pull server's SSL Certificate.
PullServerCertCN: The domain extention in this field must match the domain extention in the DSC server FQDN
Valid From: Date on which the certificate becomes valid.
Valid To: Date on which the certificate becomes invalid.

Default LCM Settings
(These are advance settings for people that know how the DSC technology works) Default LCM Settings: allows the user to set advance *LCM settings for groups or nodes (not part of a group) to inherit for default values. *LCM stands for Local Configuration Manager which is what controls applying Microsoft DSC technology. More information about LCM: https://docs.microsoft.com/en-us/powershell/dsc/metaconfig

Click the Update button to enable editing of the fields.
Customize: Toggle to inherit group or default LCM settings. Default LCM settings are inherited if the node is not part of a group. If node is part of a group then the group LCM settings are inherited.
Config Mode: Configuration Mode can be set to change the way the LCM applies configurations
Apply Only: Apply the configuration only.
Apply and Monitor: Applies the configuration and reports if a machines state no longer matches the expected configuration.
Apply and AutoCorrect: Applies the configuration and if the machines state no longer matches the configuration then reapplies the previous configuration to get back to expected state.
LCM Refresh Frequency Mins: The time interval, in minutes, at which the LCM checks a pull service to get updated configurations. The default value is 30..
LCM Config Mode Frequency Mins: How often, in minutes, the current configuration is checked and applied. This property is ignored if the ConfigurationMode property is set to ApplyOnly. The default value is 15
LCM Status Retention Time in Days: The number of days the LCM keeps the status of the current configuration

DSC Dashboard
From the Dashboard, you can work with Nodes or Groups. When you launch the DSC Server, the dashboard is displayed. You can view a list of ALL NODES or GROUPS and information about the update status.
Groups
Nodes are organized into groups. DSC includes a DEFAULT group and you can create as many custom groups as needed. For example, you can create groups based on functionality (e.g. place all Proxy Only installations into a separate group). If no other group is selected, new nodes are added to the DEFAULT group.
On the DSC home screen, click the Groups tab. A list of defined node groups is displayed on the left. When you select a group, a list of the nodes that belong to the group is displayed in the pane. On this screen, you can add groups and view/edit group settings.
Notes about Adding Nodes to Groups

  • Point to a group's POA (root authority or lower) to query all the machines in the enterprise ‘tree' and automatically add them to the group
  • When importing nodes, the DSC server will retrieve the needed info about each node from the CONTROLLERS table of the POA.
  • You can update "child" nodes that are only discoverable through local networks (Requires sending the updates through a "Parent" that is discoverable and has visibility to the child node.)

Add a group

  1. Click the icon with a plus sign.    
  2. Enter Group Details. Group Name: Friendly name of the group; Group Address: Group address is the physical address of a POA used for the check server command to quickly add nodes from the POA controller record; Profile: The default profile for nodes added to the group    
  3. Enter Credentials. User Name: Default username for nodes inheriting group credentials. User name should be fully qualified. If on a domain username should look like "retailpro\DSCUser" or if not on a domain "TargetNodeAddress\DscUser"; Password: Default password for above user to be used as inherited credentials for nodes part of said group.    
  4. Enter Default Maintenance Settings (Same as the default maintenance settings for nodes; See the New Node section for more information).
  5. Enter Default LCM Settings (Same as the default LCM settings for nodes; See the New Node section for more information).   

Import Nodes into Group

The Import Nodes feature enables you to import nodes for a group. This feature save you the trouble of having to manually add the individual node records. Click the Check Server button. DSC will query the Group's POA Controller table and get a list of Prism Servers that are joined to that POA. Proxy-only installations are not included.

  1. Select a group and then click the Check Server button.    
  2. The DSC Server calls out to the POA server gets a list of the nodes controlled by that POA.    
  3. Select the nodes to import and click Import.    

Configuring Login Credentials
If you are on a Windows Domain, the system will automatically use the local Domain username and password. If you are not on a Windows Domain, you must enter the local login information manually.
Configuring Deviations from the Group Standard
If the node being imported has a different configuration than the other nodes, edit the node. For example, if the settings are for "All Components", and the node uses a MySQL database, the Prism Server component is not needed. In such a case, you must go into the node record and edit it so that only the Prism Proxy is included.

Add Node to Group (by tapping "New Node" button)
On the DSC Dashboard, in the Groups area, highlight a group. Click the New Node button.  In the pop-up dialog, enter the address or FQDN of the node to be added. You can start typing the machine name and then use auto-complete.

Nodes
A node is a Prism server that is under the control of the DSC server when it comes to updates/upgrades. If the nodes are on the same network as the DSC Server, you can import the nodes. If the notes are on a remote network, you will have to add the node records manually. . In the case of Proxy-only installations, you must add the node records manually because the Proxy is not in the CONTROLLERS table. Nodes can be added individually or as a group (see Import Nodes)
Node Configuration Requirements

  • Windows 7, Windows 10 and Windows 2012 server platforms supported
  • Lowest acceptable version of Prism is 1.9.5.665
  • Target login and password have to be known at the DSC server
  • There may be a POA in between the DSC server and nodes
  • All machines taking part in the DSC Prism deployment must have the CACert Root Authority certificate and the Retail Pro CodeSign Certificate installed.
  • Powershell 5.1 required
  • The target must have complete trust with the server established for DSC to work, via the SET-EXECUTION POLICY command in PowerShell
  • Enable Powershell Remoting
  • Set Trusted Hosts to include the IP Address of the DSC Server
  • Set Firewalls appropriately to allow traffic between the node and the DSC Server

New Node
1.    From the DSC home screen, make sure the All Nodes tab is selected.    
2.    Click New Node.    
3.    Enter information for the node and then save the record. When you create a new node, you define the following information:

  • Node Details - Name, IP Address, Profile
  • Credentials - Username and password used to connect to the node
  • Database Credentials - Database type and username/password used to connect to DB
  • Maintenance Settings - Define the daily maintenance window during which updates will take place

Refer to the tables that follow for information about the node fields.    

New Node - Details
The first section prompts you to enter general information to identify the node.

Field Description
Node Name Enter a user-friendly name for the node.
Address Node address is the physical address of a POA used for the check server command to quickly add nodes from the POA controller record. (See Check server section for more details)
Profile The default profile for nodes added to the node.
Node parent Displays a list of other nodes in this group to be selected as the parent node. (See Node Parent/Child concept section below)


Node - Credentials

Field Description
Use Default/Group Credentials Toggle to inherit credentials set during new group creation.
Username/Password Username for node. User name should be fully qualified. If node is on a domain username should look like "retailpro\DSCUser" or if not on a domain "TargetNodeAddress\DscUser"
Enter password for the specified user


Node - Database Credentials
 

Field Description
Database Type Database type has 3 options
Retail Pro Oracle: When selected fields 2 and 3 are no longer available as we know the retail pro oracle DB username and password
Client Oracle: used when prism was installed on a standalone existing oracle client
Client MySQL: used when prism was installed on a standalone existing mysql client
Database Username  Only needed if client oracle or client mysql selected
Database password Only needed if client oracle or client mysql selected


Node - Maintenance Settings
This area enables you to control the conditions under which an update is allowed to take place. Maintenance window values control when an update can be applied to target machine. The installers will only run if the machine is in its current maintenance window.

Field Description
DSC Staging Directory Toggle to inherit group or default maintenance settings. Default maintenance settings are inherited if the node is not part of a group. If node is part of a group then the group maintenance settings are inherited. The DSC staging directory is where target nodes will store local data including the installers to be run on the machine
Time Zone Time zone which the node resides in
Maintenance Window Start Time *maintenance window start time
Maintenance Window Stop Time *maintenance window stop time

Node - Local Configuration Manager (LCM) Settings
The Local Configuration Manager (LCM) settings allow advanced users to set LCM settings for groups or nodes  that are not part of a group to inherit for default values. *LCM stands for Local Configuration Manager which is what controls applying Microsoft DSC technology. More information about LCM is available here: https://docs.microsoft.com/en-us/powershell/dsc/metaconfig

Field Description
Customize Toggle to inherit group or default LCM settings. Default LCM settings are inherited if the node is not part of a group. If node is part of a group then the group LCM settings are inherited.
Config Mode Configuration Mode can be set to change the way the LCM applies configurations:
Apply Only: Apply the configuration only.
Apply and Monitor: Applies the configuration and reports if a machines state no longer matches the expected configuration.
Apply and AutoCorrect: Applies the configuration and if the machines state no longer matches the configuration then reapplies the previous configuration to get back to expected state.
LCM Refresh Frequency Mins The time interval, in minutes, at which the LCM checks a pull service to get updated configurations. The default value is 30.
LCM Config Mode Frequency Mins How often, in minutes, the current configuration is checked and applied. This property is ignored if the ConfigurationMode property is set to ApplyOnly. The default value is 15
LCM Status Retention Time in Days The number of days the LCM keeps the status of the current configuration.


Add Prism Builds to Installers Folder
To make Prism builds available for assignment in DSC, you must place the files for the build in the \Retail Pro DSC Enterprise\Installers folder. Each set of Prism installation files is contained in a folder named "Prism 1.xx.x.xxx". For example: Prism 1.11.0.875. Copy the entire folder to the Retail Pro DSC Enterprise\Installers folder. When a new Prism versions is relased, you can copy the files to the \Retail Pro DSC Enterprise\Installers folder and deploy the update via DSC.

Update Nodes

  1. Navigate to the Groups area. Select a group.
  2. Select the individual nodes that you want to update.
  3. Click Update.

Node Parent/Child Concept
The goal of the parent and child concept is to be able to update nodes that are on private networks and not visible to the DSC host machine. In the below diagram we would select Node 1 as the parent of Node 2 since node 2 is on a private network that is visible to node 1 and not visible to the DSC host machine. When a child node is updated by the DSC host the Retail Pro DSC application runs the required configurations steps on the parent machine so that we can update the child node in a nonvisible network.

Node Status History

The Node History feature enables you to review the updates and upgrades for a node. On either the ALL NODES or GROUPS pane, if you hover the cursor over the icon between the Status and Version columns, you will see a tool tip that says "Show Status History". Click the icon. A list of updates and upgrades for the node are displayed. Select an entry in the list. The Product Details section displays the individual Prism components included.
 
Certificates (SSL, CodeSign)
All machines taking part in the DSC Prism deployment must have the following certificates:

  • CACert Root Authority certificate installed in the browser's Trusted Root Certificate Store
  • Retail Pro Code Sign Certificate installed in

SSL Certificates
The client nodes must have, in the browser's Trusted Certificate Root Store, the certificate of the root CA that issued the certificate to the DSC Server. In most cases, this will be certificate-issuing authority such as Verisign, GoDaddy, or Comodo. These CAs, as well as many others, have their certificates installed by default in all the major browsers. If you created your own certs, via an internal PKI for example, then you must distribute the root CA's cert to the nodes and manually install to the browser's Trusted Root Store.
Profiles
Profiles determine the resources and other elements that will be deployed when the profile is assigned to a node. If you click the Profiles tab on the DSC Dashboard, the page displays the list of all profiles that can be applied to nodes. Each profile is listed with its corresponding products that are included in the profile. Each profile that you define will have a different combination of Prism components. For example, you can have an "All Components" profile that includes all components. You can also have a "Proxy Only" profile that only installs the Prism Proxy on target nodes.