Whitepaper Vijeo Citect Run as a Windows Service Dec2013
Content
Vijeo Citect run as a Windows service December 2013 / White Paper
Olivier Vallee Validation Specialist
Make the most of your energy
Vijeo Citect run as a Windows service
Summary
Introduction .......................................................................................... p. 01 Session Isolation .................................................................................. p. 04 OPC Servers ………….......................................................................... p. 04 Data Collectors …………...................................................................... p. 05 Service Manager .................................................................................. p. 05 OPC DCOM Security …………….......................................................... p. 10 System Parameters .............................................................................. p. 11 Windows Services ................................................................................ p. 11 Client UI …………................................................................................. p. 12 Monitoring Servers ............................................................................... p. 13 Controlling Servers ............................................................................... p. 14 Services Manager ................................................................................ p. 15 Diagnostics ........................................................................................... p. 15 Conclusion ........................................................................................... p. 16
White Paper - December 2013
Vijeo Citect run as a Windows service
Introduction This white paper describes how to set up the StruxureWare SCADA Expert Vijeo Citect™ product to run as a Windows service. We will refer to the product as Vijeo Citect for the remainder of the white paper. Historically the Vijeo Citect product has not supported the ability to run as a Windows service. With the assistance of a third party tool, it is possible to run Vijeo Citect as a Windows service. This solution is now supported for Vijeo Citect v7.40 and higher as per scenarios documented in this white paper. The ability to run as a Windows service is crucial for many applications where the server provides runtime and historical data to clients. For these applications, a service interruption cannot be tolerated. Normally an application that only supports stand-alone program operation is forced to shut down when a log out occurs on the host machine. When run as a Windows service, the application can continue to supply data across user log in sessions. This allows the application to run unattended with no user account required to be logged into the Server. The application can also be started automatically at system power on. This provides security benefits as well as efficiency improvements of not having to have a user logged in to the operating system. It also provides a true server/client architecture where the server hardware is only used as a SCADA server. Access to this server is then restricted and locked down. In summary, the main benefits to run as a Windows service are:
Efficient use of resources
Increased security
High availability
True client/server architecture
This white paper goes through the detailed instructions to implement this functionality, including step-bystep examples. Any limitations with the proposed implementation will also be discussed and explored with the most effective approach to be taken, with a view for securing your system and providing a robust outcome.
White Paper - December 2013
01
Vijeo Citect run as a Windows service
Audience The content of this white paper is targeted towards SCADA engineers, systems integrators and individuals with intermediate to advanced level of knowledge using Vijeo Citect. In addition to this requirement, some level of IT experience would be advantageous. Users who want to run the Vijeo Citect application as a Windows service should refer to this white paper.
Prerequisites Before continuing with the setup, it is recommended to review the prerequisites:
Windows Server® 2008 / 2012 (also works on Windows 7 / 8 but recommended for server operating systems)
Vijeo Citect v7.40 or higher
NSSM v2.21.1 or higher (free service manager tool)
In addition to the above requirements, it is recommended that you have a Vijeo Citect project compiled and ready to run, and only attempt to run it as a Windows service at the final stage of system delivery. A “Runtime Only” installation is also recommended.
White Paper - December 2013
02
Vijeo Citect run as a Windows service
02
Making permanent Setting VijeoActive Citect savingsup thrugh to run asEfficiency a Energy Windows service
White Paper - December 2013
Vijeo Citect run as a Windows service
Server Isolation System and service processes run on Session 0, with user processes run on Session 1, 2 and so on. This means that system/service and user processes are isolated. If a service or application is compromised, it doesn’t necessarily mean the entire system is vulnerable. Applications that run as a Windows service with the minimum privileges required will also restrict any attacker actions.
There are some drawbacks that need to be considered when an application is run on Session 0:
Services can’t display UI on the user’s desktop
No shared resources between services
These limitations can be overcome through alternate methods or approaches. This is beyond the scope of this white paper, but further reading material can be found on the Microsoft website.
See the Microsoft PowerPoint on session isolation for further details: http://bit.ly/18YWRX5
OPC Server (optional) The following section is optional and only relevant for systems configured to run with OPC Servers. OPC servers in operation on the machine can also be configured to run as a Windows service so they can be linked to the Vijeo Citect services that will be created in a later step. Please consult the individual OPC Server product documentation for further details on how to configure the application to run as a Windows service.
OFS Service The configuration of OFS to run as a Windows service is only required if the OFSOPC driver is configured within your Vijeo Citect project. If OFS is launched by Vijeo Citect when run as a Windows service and you attempt to launch the OFS application or connect to OFS using a logged in user, it will launch another instance of OFS.exe as the interactive user account in Session 1. It is recommended that only a single OFS.exe instance be in operation, and accessible by both services and interactive users. Therefore it is necessary to configure OFS to run as a Windows service. Please consult the OFS user documentation for further details regarding the OFS Service and DCOM configuration.
White Paper - December 2013
04
Vijeo Citect run as a Windows service
Data Collectors (optional) If a configured driver in the project has a dependency on another application for data (for example PSDirect, LON, FINS, etc.) it may be necessary to adjust certain settings to operate correctly. It is beyond the scope of this white paper to explore all the possible options and configuration required. It should be understood that the I/O Server is running under Session 0 as the Local System account, and will attempt to launch any applications in the same session and user account. Therefore special consideration should be taken so that the application can run in Session 0 under the Local System account as expected. Things to consider are security privileges the Local System account inherits and whether resources the application will try to access require additional privileges. It may be necessary to elevate the service to run under a different account. For example the Network Service account may be required for applications requiring access to network resources or file shares. It is recommended that the principle of least privilege be used when setting up this user account and service.
Service Manager The Service Manager selected for the task of managing the Vijeo Citect application is NSSM. It is open source software and free to use. NSSM has many benefits which include the smooth handling of unexpected interruptions, automatically restarting applications, monitoring applications and performing certain actions on shutdown. More details about NSSM can be found at www.nssm.cc.
Installation Once NSSM has been downloaded to the target machine, it is simply copied to the windows system directory (%windir%\system32). There is no installation required, hence if you want to remove NSSM from the computer, simply delete the nssm.exe file from the Windows system directory.
Create Services Vijeo Citect v7.40 has seven process types which may require a service to manage and control each component. It is possible to have several process types when redundancy or more than one cluster is configured to run on the same machine. The seven component types are:
Client
I/O Server
Trend Server
Alarm Server
Report Server
OPC DA Server (the Vijeo Citect SCADA OPC DA Server)
EcoStruxure Web Services (EWS) Server
White Paper - December 2013
05
Vijeo Citect run as a Windows service
The services that need to be created will depend on the specific project configuration. To confirm the name and type of components in use in the project, run the computer setup Wizard on an Engineering Workstation where the project is being developed and progress through to the CPU Setup section.
Take note of the component names listed, as these will be required in the following configuration steps. Also observe that the Client, OPCDAServer and EWSServer don’t have a cluster prefix. This means that they give you a combined view of the system and configured clusters. It also means that you can run several I/O Server, Alarm, Trend and Report processes from different clusters on the same machine. Each specific process will require its own service to be created. The next step will be to use nssm.exe to create the services required and link them to the specific project settings. Launch a windows command prompt using Administrator privilege and install the first service using the nssm command: nssm install CitectClient The following window will appear:
White Paper - December 2013
06
Vijeo Citect run as a Windows service
Configure Services The NSSM service installer GUI will require several sections to be completed before creating the service. First the application path to Vijeo Citect needs to be set. Using the browse button, navigate to the bin directory and select Citect32.exe. The Startup directory will automatically take the path where the application is located. The "Options" field needs to be set for the Vijeo Citect application to operate correctly. Enter the following information in the options field: /i“C:\ProgramData\Schneider Electric\Vijeo Citect 7.40\Config\citect.ini” /r[c:Client] /d
The /i switch in the above example is optional and only required if a specific citect.ini needs to be loaded for the specific component. Take special note that there is no space between /i and the quotes enclosing the path. Further examples provided will not include this option. Check that the service name is set appropriately, as this will be the display name in the Windows Management Service Console. Then press the "Install service" button. The following confirmation should appear:
The Service "CitectClient" has successfully been created. Repeat the above steps for the other components using the information contained in the table below:
Component Name
Options
Service Name Application
Client
/r[c:Client] /d
CitectClient
Citect32.exe
Cluster1.IOServer
/r[i:Cluster1.IOServer] /d
CitectIO
Citect32.exe
Cluster1.AlarmServer1
/r[a:Cluster1.AlarmServer1] /d
CitectAlarm
Citect32.exe
Cluster1.TrendServer1
/r[t:Cluster1.TrendServer1] /d
CitectTrend
Citect32.exe
Cluster1.ReportServer1 /r[r:Cluster1.ReportServer1] /d CitectReport
Citect32.exe
OPCDAServer
/r[o:OPCDAServer] /d
CitectOPCDA
SE.SCADA.OPC.DaServer.Host.exe
EWSServer
/r[e:EWSServer] /d
CitectEWS
SE.SCADA.EWS.Server.exe
White Paper - December 2013
07
Vijeo Citect run as a Windows service
Take note of the application required for each component. The Citect32.exe application is only used for the Client, I/O, Trend and Alarm components. The OPC DA Server and EWS Server have their own specific application. It is only necessary to create services that are required by the project configuration. If you don't plan to use the OPCDAServer component, there is no need to then create the CitectOPCDA service. Similarly if you don't plan to use the EWS Server or you don’t have one defined in your project, then it is not necessary to create the CitectEWS service. At a minimum you should have the Client and I/O Server processes running as a Windows service. The other components are optional. It is possible to create additional services if you need to run more than one cluster on the same physical machine. It is also possible to run more than one I/O Server (belonging to the same Cluster) on the same machine. The additional clusters only apply to I/O Server, Alarm, Trend and Report components. There can only be one instance of a service for Client, EWS and the SCADA OPC DA Server on the same machine.
Service Dependency Once the initial creation of services has been completed, it is necessary to configure dependencies between each service. In the following example, the FlexNet Licensing Service is used for licensing, so it will need to be the first service to be started. The Vijeo Citect processes have a dependency on the Client process for licensing and the CTAPI server, hence it will need to be the second process to start. The I/O Server will then be the data source for the other processes, which will be the third to start. The other processes (SCADA OPC DA Server, Trend, Alarm, Report and EWS) will start after the I/O Server service.
To configure the dependency illustrated above, launch the registry editor (regedit.exe).
White Paper - December 2013
08
Vijeo Citect run as a Windows service
Locate the services section in the Windows registry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services Locate the Vijeo Citect services created previously. Select the CitectClient folder and right click on the white space where the other parameters are shown. Select New -> String Value:
Type in the name DependOnService, then edit the String Value and enter “FlexNet Licensing Service”:
Repeat this for each of the Services created, add a String Value (REG_SZ) called "DependOnService". Set the value based on the dependencies in the table below:
Service
Value name
Value data
CitectClient
DependOnService
FlexNet Licensing Service
CitectIO
DependOnService
CitectClient
CitectAlarm
DependOnService
CitectIO
CitectReport
DependOnService
CitectIO
CitectTrend
DependOnService
CitectIO
CitectOPCDA
DependOnService
CitectIO
CitectEWS
DependOnService
CitectIO
If the FlexNet Licensing Service is not installed and a physical dongle is attached to the machine, then leave the value data blank for the CitectClient.
White Paper - December 2013
09
Vijeo Citect run as a Windows service
OPC DCOM Security (optional) It is necessary to configure DCOM for the Vijeo Citect OPC DA Server to operate properly. The following steps should be followed if you require the Vijeo Citect OPC DA Server to run as a Windows service. To do this, modify the OPC DA Server settings in the registry: [HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{4B12BF21-3C60-4C48-A47F-E5F1E3BCFD34}\LocalServer32]
Set the Application Level to “Default” in the General tab. Then in the Identity tab, select “The launching user” as the user account to run the application.
Click OK. It is necessary to restart the machine for changes to take effect.
White Paper - December 2013
10
Vijeo Citect run as a Windows service
System Parameters Before restarting the operating system and allowing Vijeo Citect to run as a Windows service, a few Citect.ini parameters need to be adjusted for correct operation. When Vijeo Citect is run as a Windows service, it is only meant for use in networked systems hence the following parameter needs to be set: [TCP] LAN=1 To allow users to log on and log off the machine without shutting down Vijeo Citect, enable the WinShutdown parameter: [Kernel] WinShutdown=1
Windows Services The following services are now configured and ready to start on the next system restart. It is now possible to log in and log off without disrupting or stopping the Vijeo Citect system. It should be noted that the services run as Local System account on Session 0. When an application is run in Session 0 it is not possible to raise this session to the active desktop to interact with it. It will remain hidden. See the section Display UI below for further details on how to setup an interactive client session.
Make sure that the “Startup Type” is set to “Automatic” then reboot the machine to allow Vijeo Citect to run as a Windows service.
White Paper - December 2013
11
Vijeo Citect run as a Windows service
Client UI (optional) The Client process running as a Service is running in Session 0 which is not able to interact with the desktop. This process uses a full license. If you require a client display to interact with on the server machine, you will require an additional license. This can be either a Control Client license on the local machine or a floating Display Client license available on the network. It will be necessary to follow the steps detailed below. Because the Client process and other components run as a Windows service in Session 0, it is necessary to launch another Client process which is able to interact with the active desktop. To do this, create a copy of the Vijeo Citect Runtime shortcut and edit its properties. It is necessary to add the /x parameter to the target: "C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /x It is also possible to launch the Client UI and load a specific citect.ini file. This may be required if you need to launch specific startup cicode in the Vijeo Citect Client process with UI capabilities, which is different to the Client process which is run as a Windows service. To modify which citect.ini file is loaded add the /i switch with the full path to the file. An example would be: "C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /i“C:\Custom Citect Config\citect.ini” /x
A control client license (or view only license if configured) will be required by the client process. The first client process which is run as a Windows service will consume a full license (shared between other processes which also run as a Windows service).
White Paper - December 2013
12
Vijeo Citect run as a Windows service
Monitoring Servers An effective way to get detailed diagnostics and status of the running system is to use the following Cicode functions: ServerGetProperty (sServer, sProperty, sCluster) The ServerGetProperty function can only be called for Alarm, Report and Trend types. It will not work for other Server types (I/O Server, OPC DA, EWS). ServerInfo (sName, iType, sCluster) The ServerInfo function only works for Alarm, Trend, Report and I/O Server types. It will not work for other Server types (OPC DA, EWS). The Example project has Cicode and graphics pages pre-configured which can be re-used to monitor the server status in your system.
White Paper - December 2013
13
Vijeo Citect run as a Windows service
Controlling Servers There are a number of options available to manage and control the servers. The traditional method is to use the ‘Citect Runtime Manager’, but this is no longer running so cannot be used. When Vijeo Citect is run as a Windows service we bypass the conventional ‘Citect Runtime Manager’, which usually manages and monitors the various Vijeo Citect processes. When Vijeo Citect is run as a Windows service, if we were to then run the ‘Citect Runtime Manager’, a duplicate instance of the processes could start, causing unknown/undesired outcomes in accessing common resources and files. As a result we have to use either Cicode, or the Windows Service Manager to control the Services and the respective servers.
WARNING UNINTENDED EQUIPMENT OPERATION
It is recommended that a “Runtime Only” installation be used on server machines.
Do not attempt to launch ‘Citect Runtime Manager’ while Services are running.
‘Citect Runtime Manager’ can interfere with processes that are running as a Service.
Failure to follow these instructions can cause death, serious injury or equipment damage.
Cicode The following Cicode functions could also be used to control the Server processes. ServerReload (sServerName, sCluster, bSync) Server reload only works on the following components: Alarm, Trend, Report. ServerRestart (sServerName, sCluster) Restart works on the following components: Alarm, Trend, Report, I/O. Shutdown (sDestination, sProject, iMode, sCluster, bCallEvent) Shutdown works on the following components: Alarm, Trend, Report, I/O, OPC DA.
White Paper - December 2013
14
Vijeo Citect run as a Windows service
Services Manager The Windows Services Manager Console allows you to manage individual services installed on the operating system. The following controls can be used on the Vijeo Citect Services created previously:
Stop
Start
Restart
The Pause mode is not supported by Vijeo Citect and will return an application error in the event viewer: "Service [ServiceName] received unsupported PAUSE control, which will not be handled" A shortcut to the Windows Services Manager Console can be added to the engineering tools page in the Vijeo Citect project. Set the following command on a button: Exec ("cmd /c services.msc")
Diagnostics Since it is not possible to directly access the kernel for individual component processes, it may be necessary to access diagnostics information through alternative methods. The following options should be explored and used as appropriate for the individual system requirements.
Event Viewer The Application Event Log is a useful source of information. The NSSM service manager will log any unexpected interruptions here. To access the event viewer go to Control Panel -> System and Security -> Administrator Tools -> Event Viewer. Click on the Application folder and locate any specific events that have nssm as their Source. For further details, consult the NSSM documentation.
Log Files Diagnostic information is also available to view in the log files automatically created by each component. The syslog.dat, debug.log, parameters.log each have useful information which aids in diagnosing any unexpected interruptions that are experienced.
Cicode The majority of information contained in the Kernel can be obtained through performing a kernel dump. The kernel dump is simply a text file which can be opened with a text editor. The kernel dump Cicode function is only supported on the following components: Alarm, Trend, Report, I/O and OPC DA. To perform a kernel dump on a specific component, run the following Cicode command from a button or other calling function: ServerRPC("<servername>","DumpKernel","0x8000, ^"^"", 1, "<clustername>") Where servername and clustername are set according to the project configuration.
White Paper - December 2013
15
Vijeo Citect run as a Windows service
Conclusion In closing, there are some important points to consider before proceeding to run Vijeo Citect as a Windows service:
Each Vijeo Citect service will run in Session 0 under the Local System account which is not able to interact with the desktop.
When Vijeo Citect is run as a Windows service under the Local System, it will not have access to network resources. For example UNC file shares, printer access and other resources may be unavailable. If these resources are required, the service effected must be run under a user account with the required privilege, for example the Network Service account. It is recommended that the principle of least privilege be used when setting up this user account and service.
There is no kernel access to components running as a Windows service. A kernel window is only available for the Client UI process if running.
One full license is required on each Server which is shared amongst all services.
If you need to access the Client UI, an additional control license is required on the Server.
There are no Cicode functions available to control or manage the OPC DA Server or EWS Server. The log files found in the log folder should be used if any unexpected interruptions are experienced.
The OPC DA Server and EWS Server are optional and can be left to the interactive user to launch.
When setting up Vijeo Citect to run as a Windows service, it is recommended to update any project deployment procedures. Care needs to be taken to not inadvertently make changes to the running system (e.g. accidentally modifying the project making it “uncompiled”). It is highly recommended to have a “Runtime Only” installation on server machines.
Vijeo Citect does not support pause mode when issued from the Windows Services Manager. If a pause command is issued, it will return an error code.
‘Citect Runtime Manager’ can no longer be used when Vijeo Citect is run as a Windows service. When Vijeo Citect is run as a Windows service, if we were to then run the ‘Citect Runtime Manager’, a duplicate instance of the processes could start, causing unknown/undesired outcomes in accessing common resources and files. It is highly recommended to have a “Runtime Only” installation on server machines.
Efficiency, increased security and high availability are just some of the values delivered when Vijeo Citect is run as a Windows service.
White Paper - December 2013
16
Schneider Electric (Australia) Pty Ltd 78 Waterloo Road Macquarie Park, NSW 2113 Phone: + 61 (2) 9125 8000 Fax: + 61 (2) 9889 5502 http://www.schneider-electric.com December 2013
White Paper - December 2013
© 2013 Schneider Electric. All rights reserved.
Vijeo Citect run as a Windows service
Olivier Vallee Validation Specialist
Make the most of your energy
Vijeo Citect run as a Windows service
Summary
Introduction .......................................................................................... p. 01 Session Isolation .................................................................................. p. 04 OPC Servers ………….......................................................................... p. 04 Data Collectors …………...................................................................... p. 05 Service Manager .................................................................................. p. 05 OPC DCOM Security …………….......................................................... p. 10 System Parameters .............................................................................. p. 11 Windows Services ................................................................................ p. 11 Client UI …………................................................................................. p. 12 Monitoring Servers ............................................................................... p. 13 Controlling Servers ............................................................................... p. 14 Services Manager ................................................................................ p. 15 Diagnostics ........................................................................................... p. 15 Conclusion ........................................................................................... p. 16
White Paper - December 2013
Vijeo Citect run as a Windows service
Introduction This white paper describes how to set up the StruxureWare SCADA Expert Vijeo Citect™ product to run as a Windows service. We will refer to the product as Vijeo Citect for the remainder of the white paper. Historically the Vijeo Citect product has not supported the ability to run as a Windows service. With the assistance of a third party tool, it is possible to run Vijeo Citect as a Windows service. This solution is now supported for Vijeo Citect v7.40 and higher as per scenarios documented in this white paper. The ability to run as a Windows service is crucial for many applications where the server provides runtime and historical data to clients. For these applications, a service interruption cannot be tolerated. Normally an application that only supports stand-alone program operation is forced to shut down when a log out occurs on the host machine. When run as a Windows service, the application can continue to supply data across user log in sessions. This allows the application to run unattended with no user account required to be logged into the Server. The application can also be started automatically at system power on. This provides security benefits as well as efficiency improvements of not having to have a user logged in to the operating system. It also provides a true server/client architecture where the server hardware is only used as a SCADA server. Access to this server is then restricted and locked down. In summary, the main benefits to run as a Windows service are:
Efficient use of resources
Increased security
High availability
True client/server architecture
This white paper goes through the detailed instructions to implement this functionality, including step-bystep examples. Any limitations with the proposed implementation will also be discussed and explored with the most effective approach to be taken, with a view for securing your system and providing a robust outcome.
White Paper - December 2013
01
Vijeo Citect run as a Windows service
Audience The content of this white paper is targeted towards SCADA engineers, systems integrators and individuals with intermediate to advanced level of knowledge using Vijeo Citect. In addition to this requirement, some level of IT experience would be advantageous. Users who want to run the Vijeo Citect application as a Windows service should refer to this white paper.
Prerequisites Before continuing with the setup, it is recommended to review the prerequisites:
Windows Server® 2008 / 2012 (also works on Windows 7 / 8 but recommended for server operating systems)
Vijeo Citect v7.40 or higher
NSSM v2.21.1 or higher (free service manager tool)
In addition to the above requirements, it is recommended that you have a Vijeo Citect project compiled and ready to run, and only attempt to run it as a Windows service at the final stage of system delivery. A “Runtime Only” installation is also recommended.
White Paper - December 2013
02
Vijeo Citect run as a Windows service
02
Making permanent Setting VijeoActive Citect savingsup thrugh to run asEfficiency a Energy Windows service
White Paper - December 2013
Vijeo Citect run as a Windows service
Server Isolation System and service processes run on Session 0, with user processes run on Session 1, 2 and so on. This means that system/service and user processes are isolated. If a service or application is compromised, it doesn’t necessarily mean the entire system is vulnerable. Applications that run as a Windows service with the minimum privileges required will also restrict any attacker actions.
There are some drawbacks that need to be considered when an application is run on Session 0:
Services can’t display UI on the user’s desktop
No shared resources between services
These limitations can be overcome through alternate methods or approaches. This is beyond the scope of this white paper, but further reading material can be found on the Microsoft website.
See the Microsoft PowerPoint on session isolation for further details: http://bit.ly/18YWRX5
OPC Server (optional) The following section is optional and only relevant for systems configured to run with OPC Servers. OPC servers in operation on the machine can also be configured to run as a Windows service so they can be linked to the Vijeo Citect services that will be created in a later step. Please consult the individual OPC Server product documentation for further details on how to configure the application to run as a Windows service.
OFS Service The configuration of OFS to run as a Windows service is only required if the OFSOPC driver is configured within your Vijeo Citect project. If OFS is launched by Vijeo Citect when run as a Windows service and you attempt to launch the OFS application or connect to OFS using a logged in user, it will launch another instance of OFS.exe as the interactive user account in Session 1. It is recommended that only a single OFS.exe instance be in operation, and accessible by both services and interactive users. Therefore it is necessary to configure OFS to run as a Windows service. Please consult the OFS user documentation for further details regarding the OFS Service and DCOM configuration.
White Paper - December 2013
04
Vijeo Citect run as a Windows service
Data Collectors (optional) If a configured driver in the project has a dependency on another application for data (for example PSDirect, LON, FINS, etc.) it may be necessary to adjust certain settings to operate correctly. It is beyond the scope of this white paper to explore all the possible options and configuration required. It should be understood that the I/O Server is running under Session 0 as the Local System account, and will attempt to launch any applications in the same session and user account. Therefore special consideration should be taken so that the application can run in Session 0 under the Local System account as expected. Things to consider are security privileges the Local System account inherits and whether resources the application will try to access require additional privileges. It may be necessary to elevate the service to run under a different account. For example the Network Service account may be required for applications requiring access to network resources or file shares. It is recommended that the principle of least privilege be used when setting up this user account and service.
Service Manager The Service Manager selected for the task of managing the Vijeo Citect application is NSSM. It is open source software and free to use. NSSM has many benefits which include the smooth handling of unexpected interruptions, automatically restarting applications, monitoring applications and performing certain actions on shutdown. More details about NSSM can be found at www.nssm.cc.
Installation Once NSSM has been downloaded to the target machine, it is simply copied to the windows system directory (%windir%\system32). There is no installation required, hence if you want to remove NSSM from the computer, simply delete the nssm.exe file from the Windows system directory.
Create Services Vijeo Citect v7.40 has seven process types which may require a service to manage and control each component. It is possible to have several process types when redundancy or more than one cluster is configured to run on the same machine. The seven component types are:
Client
I/O Server
Trend Server
Alarm Server
Report Server
OPC DA Server (the Vijeo Citect SCADA OPC DA Server)
EcoStruxure Web Services (EWS) Server
White Paper - December 2013
05
Vijeo Citect run as a Windows service
The services that need to be created will depend on the specific project configuration. To confirm the name and type of components in use in the project, run the computer setup Wizard on an Engineering Workstation where the project is being developed and progress through to the CPU Setup section.
Take note of the component names listed, as these will be required in the following configuration steps. Also observe that the Client, OPCDAServer and EWSServer don’t have a cluster prefix. This means that they give you a combined view of the system and configured clusters. It also means that you can run several I/O Server, Alarm, Trend and Report processes from different clusters on the same machine. Each specific process will require its own service to be created. The next step will be to use nssm.exe to create the services required and link them to the specific project settings. Launch a windows command prompt using Administrator privilege and install the first service using the nssm command: nssm install CitectClient The following window will appear:
White Paper - December 2013
06
Vijeo Citect run as a Windows service
Configure Services The NSSM service installer GUI will require several sections to be completed before creating the service. First the application path to Vijeo Citect needs to be set. Using the browse button, navigate to the bin directory and select Citect32.exe. The Startup directory will automatically take the path where the application is located. The "Options" field needs to be set for the Vijeo Citect application to operate correctly. Enter the following information in the options field: /i“C:\ProgramData\Schneider Electric\Vijeo Citect 7.40\Config\citect.ini” /r[c:Client] /d
The /i switch in the above example is optional and only required if a specific citect.ini needs to be loaded for the specific component. Take special note that there is no space between /i and the quotes enclosing the path. Further examples provided will not include this option. Check that the service name is set appropriately, as this will be the display name in the Windows Management Service Console. Then press the "Install service" button. The following confirmation should appear:
The Service "CitectClient" has successfully been created. Repeat the above steps for the other components using the information contained in the table below:
Component Name
Options
Service Name Application
Client
/r[c:Client] /d
CitectClient
Citect32.exe
Cluster1.IOServer
/r[i:Cluster1.IOServer] /d
CitectIO
Citect32.exe
Cluster1.AlarmServer1
/r[a:Cluster1.AlarmServer1] /d
CitectAlarm
Citect32.exe
Cluster1.TrendServer1
/r[t:Cluster1.TrendServer1] /d
CitectTrend
Citect32.exe
Cluster1.ReportServer1 /r[r:Cluster1.ReportServer1] /d CitectReport
Citect32.exe
OPCDAServer
/r[o:OPCDAServer] /d
CitectOPCDA
SE.SCADA.OPC.DaServer.Host.exe
EWSServer
/r[e:EWSServer] /d
CitectEWS
SE.SCADA.EWS.Server.exe
White Paper - December 2013
07
Vijeo Citect run as a Windows service
Take note of the application required for each component. The Citect32.exe application is only used for the Client, I/O, Trend and Alarm components. The OPC DA Server and EWS Server have their own specific application. It is only necessary to create services that are required by the project configuration. If you don't plan to use the OPCDAServer component, there is no need to then create the CitectOPCDA service. Similarly if you don't plan to use the EWS Server or you don’t have one defined in your project, then it is not necessary to create the CitectEWS service. At a minimum you should have the Client and I/O Server processes running as a Windows service. The other components are optional. It is possible to create additional services if you need to run more than one cluster on the same physical machine. It is also possible to run more than one I/O Server (belonging to the same Cluster) on the same machine. The additional clusters only apply to I/O Server, Alarm, Trend and Report components. There can only be one instance of a service for Client, EWS and the SCADA OPC DA Server on the same machine.
Service Dependency Once the initial creation of services has been completed, it is necessary to configure dependencies between each service. In the following example, the FlexNet Licensing Service is used for licensing, so it will need to be the first service to be started. The Vijeo Citect processes have a dependency on the Client process for licensing and the CTAPI server, hence it will need to be the second process to start. The I/O Server will then be the data source for the other processes, which will be the third to start. The other processes (SCADA OPC DA Server, Trend, Alarm, Report and EWS) will start after the I/O Server service.
To configure the dependency illustrated above, launch the registry editor (regedit.exe).
White Paper - December 2013
08
Vijeo Citect run as a Windows service
Locate the services section in the Windows registry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services Locate the Vijeo Citect services created previously. Select the CitectClient folder and right click on the white space where the other parameters are shown. Select New -> String Value:
Type in the name DependOnService, then edit the String Value and enter “FlexNet Licensing Service”:
Repeat this for each of the Services created, add a String Value (REG_SZ) called "DependOnService". Set the value based on the dependencies in the table below:
Service
Value name
Value data
CitectClient
DependOnService
FlexNet Licensing Service
CitectIO
DependOnService
CitectClient
CitectAlarm
DependOnService
CitectIO
CitectReport
DependOnService
CitectIO
CitectTrend
DependOnService
CitectIO
CitectOPCDA
DependOnService
CitectIO
CitectEWS
DependOnService
CitectIO
If the FlexNet Licensing Service is not installed and a physical dongle is attached to the machine, then leave the value data blank for the CitectClient.
White Paper - December 2013
09
Vijeo Citect run as a Windows service
OPC DCOM Security (optional) It is necessary to configure DCOM for the Vijeo Citect OPC DA Server to operate properly. The following steps should be followed if you require the Vijeo Citect OPC DA Server to run as a Windows service. To do this, modify the OPC DA Server settings in the registry: [HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{4B12BF21-3C60-4C48-A47F-E5F1E3BCFD34}\LocalServer32]
Set the Application Level to “Default” in the General tab. Then in the Identity tab, select “The launching user” as the user account to run the application.
Click OK. It is necessary to restart the machine for changes to take effect.
White Paper - December 2013
10
Vijeo Citect run as a Windows service
System Parameters Before restarting the operating system and allowing Vijeo Citect to run as a Windows service, a few Citect.ini parameters need to be adjusted for correct operation. When Vijeo Citect is run as a Windows service, it is only meant for use in networked systems hence the following parameter needs to be set: [TCP] LAN=1 To allow users to log on and log off the machine without shutting down Vijeo Citect, enable the WinShutdown parameter: [Kernel] WinShutdown=1
Windows Services The following services are now configured and ready to start on the next system restart. It is now possible to log in and log off without disrupting or stopping the Vijeo Citect system. It should be noted that the services run as Local System account on Session 0. When an application is run in Session 0 it is not possible to raise this session to the active desktop to interact with it. It will remain hidden. See the section Display UI below for further details on how to setup an interactive client session.
Make sure that the “Startup Type” is set to “Automatic” then reboot the machine to allow Vijeo Citect to run as a Windows service.
White Paper - December 2013
11
Vijeo Citect run as a Windows service
Client UI (optional) The Client process running as a Service is running in Session 0 which is not able to interact with the desktop. This process uses a full license. If you require a client display to interact with on the server machine, you will require an additional license. This can be either a Control Client license on the local machine or a floating Display Client license available on the network. It will be necessary to follow the steps detailed below. Because the Client process and other components run as a Windows service in Session 0, it is necessary to launch another Client process which is able to interact with the active desktop. To do this, create a copy of the Vijeo Citect Runtime shortcut and edit its properties. It is necessary to add the /x parameter to the target: "C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /x It is also possible to launch the Client UI and load a specific citect.ini file. This may be required if you need to launch specific startup cicode in the Vijeo Citect Client process with UI capabilities, which is different to the Client process which is run as a Windows service. To modify which citect.ini file is loaded add the /i switch with the full path to the file. An example would be: "C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /i“C:\Custom Citect Config\citect.ini” /x
A control client license (or view only license if configured) will be required by the client process. The first client process which is run as a Windows service will consume a full license (shared between other processes which also run as a Windows service).
White Paper - December 2013
12
Vijeo Citect run as a Windows service
Monitoring Servers An effective way to get detailed diagnostics and status of the running system is to use the following Cicode functions: ServerGetProperty (sServer, sProperty, sCluster) The ServerGetProperty function can only be called for Alarm, Report and Trend types. It will not work for other Server types (I/O Server, OPC DA, EWS). ServerInfo (sName, iType, sCluster) The ServerInfo function only works for Alarm, Trend, Report and I/O Server types. It will not work for other Server types (OPC DA, EWS). The Example project has Cicode and graphics pages pre-configured which can be re-used to monitor the server status in your system.
White Paper - December 2013
13
Vijeo Citect run as a Windows service
Controlling Servers There are a number of options available to manage and control the servers. The traditional method is to use the ‘Citect Runtime Manager’, but this is no longer running so cannot be used. When Vijeo Citect is run as a Windows service we bypass the conventional ‘Citect Runtime Manager’, which usually manages and monitors the various Vijeo Citect processes. When Vijeo Citect is run as a Windows service, if we were to then run the ‘Citect Runtime Manager’, a duplicate instance of the processes could start, causing unknown/undesired outcomes in accessing common resources and files. As a result we have to use either Cicode, or the Windows Service Manager to control the Services and the respective servers.
WARNING UNINTENDED EQUIPMENT OPERATION
It is recommended that a “Runtime Only” installation be used on server machines.
Do not attempt to launch ‘Citect Runtime Manager’ while Services are running.
‘Citect Runtime Manager’ can interfere with processes that are running as a Service.
Failure to follow these instructions can cause death, serious injury or equipment damage.
Cicode The following Cicode functions could also be used to control the Server processes. ServerReload (sServerName, sCluster, bSync) Server reload only works on the following components: Alarm, Trend, Report. ServerRestart (sServerName, sCluster) Restart works on the following components: Alarm, Trend, Report, I/O. Shutdown (sDestination, sProject, iMode, sCluster, bCallEvent) Shutdown works on the following components: Alarm, Trend, Report, I/O, OPC DA.
White Paper - December 2013
14
Vijeo Citect run as a Windows service
Services Manager The Windows Services Manager Console allows you to manage individual services installed on the operating system. The following controls can be used on the Vijeo Citect Services created previously:
Stop
Start
Restart
The Pause mode is not supported by Vijeo Citect and will return an application error in the event viewer: "Service [ServiceName] received unsupported PAUSE control, which will not be handled" A shortcut to the Windows Services Manager Console can be added to the engineering tools page in the Vijeo Citect project. Set the following command on a button: Exec ("cmd /c services.msc")
Diagnostics Since it is not possible to directly access the kernel for individual component processes, it may be necessary to access diagnostics information through alternative methods. The following options should be explored and used as appropriate for the individual system requirements.
Event Viewer The Application Event Log is a useful source of information. The NSSM service manager will log any unexpected interruptions here. To access the event viewer go to Control Panel -> System and Security -> Administrator Tools -> Event Viewer. Click on the Application folder and locate any specific events that have nssm as their Source. For further details, consult the NSSM documentation.
Log Files Diagnostic information is also available to view in the log files automatically created by each component. The syslog.dat, debug.log, parameters.log each have useful information which aids in diagnosing any unexpected interruptions that are experienced.
Cicode The majority of information contained in the Kernel can be obtained through performing a kernel dump. The kernel dump is simply a text file which can be opened with a text editor. The kernel dump Cicode function is only supported on the following components: Alarm, Trend, Report, I/O and OPC DA. To perform a kernel dump on a specific component, run the following Cicode command from a button or other calling function: ServerRPC("<servername>","DumpKernel","0x8000, ^"^"", 1, "<clustername>") Where servername and clustername are set according to the project configuration.
White Paper - December 2013
15
Vijeo Citect run as a Windows service
Conclusion In closing, there are some important points to consider before proceeding to run Vijeo Citect as a Windows service:
Each Vijeo Citect service will run in Session 0 under the Local System account which is not able to interact with the desktop.
When Vijeo Citect is run as a Windows service under the Local System, it will not have access to network resources. For example UNC file shares, printer access and other resources may be unavailable. If these resources are required, the service effected must be run under a user account with the required privilege, for example the Network Service account. It is recommended that the principle of least privilege be used when setting up this user account and service.
There is no kernel access to components running as a Windows service. A kernel window is only available for the Client UI process if running.
One full license is required on each Server which is shared amongst all services.
If you need to access the Client UI, an additional control license is required on the Server.
There are no Cicode functions available to control or manage the OPC DA Server or EWS Server. The log files found in the log folder should be used if any unexpected interruptions are experienced.
The OPC DA Server and EWS Server are optional and can be left to the interactive user to launch.
When setting up Vijeo Citect to run as a Windows service, it is recommended to update any project deployment procedures. Care needs to be taken to not inadvertently make changes to the running system (e.g. accidentally modifying the project making it “uncompiled”). It is highly recommended to have a “Runtime Only” installation on server machines.
Vijeo Citect does not support pause mode when issued from the Windows Services Manager. If a pause command is issued, it will return an error code.
‘Citect Runtime Manager’ can no longer be used when Vijeo Citect is run as a Windows service. When Vijeo Citect is run as a Windows service, if we were to then run the ‘Citect Runtime Manager’, a duplicate instance of the processes could start, causing unknown/undesired outcomes in accessing common resources and files. It is highly recommended to have a “Runtime Only” installation on server machines.
Efficiency, increased security and high availability are just some of the values delivered when Vijeo Citect is run as a Windows service.
White Paper - December 2013
16
Schneider Electric (Australia) Pty Ltd 78 Waterloo Road Macquarie Park, NSW 2113 Phone: + 61 (2) 9125 8000 Fax: + 61 (2) 9889 5502 http://www.schneider-electric.com December 2013
White Paper - December 2013
© 2013 Schneider Electric. All rights reserved.
Vijeo Citect run as a Windows service
