ClearSCADA

Errors with Scripting

Are you having strange issues with scripting accessing data within ClearSCADA? Does it return a strange runtime error or just take a long time to initially execute? If so, please read this article to understand how the scripting gets the data from the ClearSCADA database, and will hopefully allow you to understand and fix the issue.

This document goes through the common causes, in decreasing order of likelihood, that will cause scripting to fail to get data rather than looking at the possible errors generated and then the possible causes. This is because the possible errors depend on the external problem, i.e. errors returned from IIS and Apache will often be different, and what exactly is being requested of the web server. Hopefully the causes however can still be traced through to a resolution of the error.

Whilst the guide does try to explain some of the basic concepts, knowledge of TCP/IP networking will greatly help the user understand the possible issues and hopefully fix any problem sooner.

Overview of Scripting

Scripting, in all versions up to and including ClearSCADA 2017 R2, is based on Microsoft’s ActiveScript and is included as part of the functionality of ViewX. It is not developed by Schneider Electric but merely extended with some custom objects. One such limitations however is that it is not possible for scripting to access database properties from ClearSCADA via the standard connection paths that the mimics and trends use, by default this is the connection to port 5481, and so must instead use the SOAP interface which is provided by the same core functionality as standard WebX. This means that when scripting needs to access ClearSCADA database properties it must open a connection to the WebX port to get that data and this can cause a few problems if there is a configuration problem!

Whenever you use the Server or Alarm.Server object in scripting, that call is requiring access to data from ClearSCADA and this request is transmitted via the WebX ports.

Example Script

The following mimic script will return an error if scripting is having issues accessing the ClearSCADA database for any reason and can be used to test your connection if needs be:

Option Explicit
Public Sub GetRootObject
  Dim Obj
  Set Obj = Server.RootObject
  MsgBox "If you are reading this your connection worked"
End Sub

Note that if your problem is another ClearSCADA database listening on the WebX ports then this script will probably still work.

What are the Possible Problems?

Port Not Listening

By default ClearSCADA’s web ports will listen for incoming connections on TCP port 80 for HTTP traffic and TCP port 443 for HTTPS traffic; the trouble is that these are also the default ports for any general purpose web server. This means that if another web server such as IIS or Apache2 is installed and left configured as their default then these are going to compete for access to that port and these services will typically start up before ClearSCADA blocking ClearSCADA from using those ports.

If that happens then when scripting tries to access the database instead of accessing ClearSCADA it will instead access whatever else is listening on that port instead. It is unlikely to be another ClearSCADA database and so it will not understand what is being requested of it and will return one of a various number of errors almost immediately to the client including ‘page not found’, ‘method error’ or ‘gateway timeout’.

If you are running multiple instances of ClearSCADA on the same machine then each instance must have its own unique ports for scripting to connect to, otherwise your scripting will probably connect to the wrong ClearSCADA database and possibly return incorrect data depending on what exactly you are requesting and how your database configuration is configured.

Symptoms of this problem will be the same on all ViewX clients, including when running ViewX on the ClearSCADA server itself.

Bear in mind that if the HTTPS port is enabled it will be used even if ClearSCADA couldn’t actually listen on that port, only if it is disabled then it will use the HTTP port.

The simplest way to see if ClearSCADA is correctly listening on the required ports using Server Status go to General -> Information and look for the lines starting with ‘HTTP Web Server:’ and ‘HTTPS Web Server:’. The following image shows what it should show with the default ports correctly listening, note that the ports you choose to use for your ClearSCADA instance may be different to the ones shown below:

If ClearSCADA is unable to listen on a port then it will be indicated as shown in the image below:

If the WebX ports are in use then the options you have are:

  • Change the WebX ports within ClearSCADA to ports which are not in use
  • Reconfigure whatever is currently listening on those ports to free that port up for ClearSCADA (a restart of ClearSCADA or a quick reconfiguration to and from the ports are needed)

To find the current user of a port use the standard Windows ‘netstat -ano’ or 'netstat -bn' commands, or the more user friendly TCPView application available from the Microsoft website.

Proxy Problems

Scripting uses the same API calls to access the ClearSCADA web server in the same way that Internet Explorer connects to Internet sites such as http://www.schneider-electric.com. This means that should you have a proxy server configured within your Windows settings then these settings will be used when trying to connect to ClearSCADA.

Typically a company’s proxy server will not know what the ClearSCADA servers are as they are an internal server, and are normally in a segregated network, and so the proxy will reject the connection and the script will either successfully connect to the server directly bypassing the proxy or report an error.

If the proxy cannot be contacted due to working remotely or being on an isolated network then you’ll typically see a delay and then suddenly scripting will work for the rest of the mimic being open. This is a fairly common problem when using standard operating environments provided by IT departments.

If you are seeing initial delays of about 20-30 seconds before an error or successful data gathering then it is usually a proxy issue. Symptoms will likely be isolated to specific machines, maybe all machines from the same image or same office location. Typically running ViewX on ClearSCADA servers is unaffected as the loopback network address should always just work.

The solution, depending on the specific cause involves removing the proxy configuration from your machine or modifying the proxy configuration (or auto configuration/PAC) to exclude the ClearSCADA servers. There is no ClearSCADA server or client-side configuration option you can change to help with this issue as it is the underlying operating system functionality that is causing the problems.

This problem is typically only seen on certain machines where there might not be a common cause. For example two machines on the same domain within the same network segment may only show the problem on one of the machines.

Port Not Contactable

Quite simply, something is blocking ViewX from connecting to the WebX port on the server. Possible causes:

  • Firewall on the server not configured to allow a connection between the machines on that port
  • Firewall on the client not expecting an outbound connection, although if using the default ports of 80 or 443 this fairly unlikely
  • Intermediate firewall on the network not having a rule in its ACL for the WebX connection
  • PAT (“NAT”) port forwarding not being configured properly
  • HIPS (Host-based Intrusion Prevention System) software on the client treating the outbound connection as suspicious and killing the connection

If this is the case then you should seek help from your system administrator and/or network administrator. As a user there is not much you can do.

In this scenario you may find that some workstations work correctly whereas other workstations do not, normally there will be a pattern to the machines which show an error (i.e. workstations in a specific office all show the same problem but those in other offices do not).

If you can open WebX on the server from a client then the port isn’t being blocked. ViewX running on the ClearSCADA server itself will also run without a problem as it will use the loopback address which will be unaffected by network and system restrictions

Certificate Revocation List (CRL) Out of Date

Industrial control systems often are not connected to the Internet and this often includes the clients. If these clients are not kept up to date with updates from Microsoft the revocation lists can get out of date and may produce various errors (such as when installing software) and may interfere with scripting’s connection to the ClearSCADA servers. If none of the above information helps with the solving of the connectivity problem then try updating the certificate information for the troublesome workstations.

The relevant links are:

Download each file, right click on the file and choose ‘Install CRL’. You need to be an administrator on the machine to import the changes.

For further information on the CRL process and how it might affect you refer to http://en.wikipedia.org/wiki/Revocation_list

Generally this problem will appear on random clients which may not show an obvious pattern.

SSL Certificate Too Short

In late 2012 Microsoft released an update to all their operating systems which blocked any certificate that is less than 1024 bits in length in an attempt to improve overall system security. Additional information is available from Microsoft at http://support.microsoft.com/kb/2661254.

When ClearSCADA starts for the very first time it generates a self-signed certificate, in recent versions they are at least 1024 bits in size however in past versions they were only 512 bits. When ClearSCADA is upgraded these certificates are not regenerated and so older systems may still carry 512-bit sized certificates with current versions of the software.

The effect is that the operating system will reject the certificate used by ClearSCADA and the WebX website will not be displayed instead showing a '404 page not found' error, yet ClearSCADA will show it is correctly listening on the ports. To verify the size of the current certificate you are using, you can do:

  1. Loading up the ClearSCADA Server Configuration tool
  2. Navigate to System Configuration -> WebX
  3. Find the location for the Certificate (in the Certificates section), the one with the *.cer extension
  4. Open up that location in Windows explorer on the ClearSCADA server
  5. Double-click the ClearSCADA.cer file
  6. Select the Details tab
  7. Scroll down to the 'Public Key' entry and the value will be the bit size, for example 'RSA (1024 bits)' is a 1024-bit key

If the size is less reported as less than 1024, renaming the key and restarting ClearSCADA will generate a new certificate of at least 1024 in size. This newly generated certificate would then need to be distributed to any WebX clients to ensure that no errors are shown when accessing the system via HTTPS. Delete the old renamed certificate once you are happy with the new certificate's functionality.

Ideally on production systems you would be using a certificate issued from a trusted CA, in which case if they have provided a certificate smaller than 1024 bits then a new certificate should be issued prior to installation of the Microsoft update.

If you are unable to regenerate or reissue certificates, the Microsoft article above provides detailed information on how to change the setting to allow smaller key sizes to be used (i.e. using 'certutil' command). This is however not recommended, at least not as a long term solution.

Still Having a Problem?

The above problems and resolutions are based on the experience of using ClearSCADA for the past few of years and seeing these problems in various environments. Each end user is unique and so the information above might not match what you’re seeing but may help point you in the right direction. If you are still having issues:

  • Ensure that the Windows operating system you are using is fully patched
  • Disable the ClearSCADA HTTPS port (temporarily) and see if that fixes the problem which may narrow down the problem area
  • Speak to Schneider Electric support, there could well be a known bug with your ClearSCADA version and the agents will be willing to help you out. They may ask for log files
  • If policy allows, review the traffic between ViewX and the ClearSCADA server using network sniffing software such as Wireshark, as this may show some interesting information that may indicate where the problems are located
  • Use independent software such as nc/ncat to verify connectivity between ports
  • Within Internet Explorer disable "Check for server certificate revocation" (Tools -> Options -> Advanced) and restart ViewX. See if that fixes the problem which helps to narrow down the cause of the error