vijeo citect run as a windows service - schneider electric · white paper - december 2013 vijeo...

Make the most of your energy

Vijeo Citect run

as a Windows service

December 2013 / White Paper

Olivier Vallee Validation Specialist

White Paper - December 2013

Vijeo Citect run as a Windows service

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

Summary



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-by-

step 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.

Introduction

01



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.

02



02

Making permanent

savings thrugh Active

Energy Efficiency

Setting up Vijeo Citect

to run as a

Windows service



OPC Server (optional)

04

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

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.

Server Isolation

http://bit.ly/18YWRX5



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.

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

Service Manager

05

Data Collectors (optional)

http://www.nssm.cc/



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:

06



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

/i“C:\ProgramData\Schneider Electric\Vijeo Citect 7.40\Config\citect.ini” /r[c:Client] /d

07

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:

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:



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).

08



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

09

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:

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.



OPC DCOM Security (optional)

[HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{4B12BF21-3C60-4C48-A47F-E5F1E3BCFD34}\LocalServer32]

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:

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.

10



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.

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

11

System Parameters



"C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /i“C:\Custom Citect Config\citect.ini” /x

"C:\Program Files (x86)\Schneider Electric\Vijeo Citect 7.40\Bin\Citect32.exe" /x

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:

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:

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).

12



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.

Monitoring Servers

13



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.

14



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

Services Manager

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.

15



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.

Conclusion

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

http://www.schneider-electric.com December 2013

http://www.schneider-electric.com

© 2

013

Sch

neid

er

Ele

ctr

ic.

All

rig

hts

re

se

rve

d.

vijeo citect run as a windows service - schneider electric · white paper - december 2013 vijeo...

Documents