Vtrin Server is a service that provides remote access to the Vtrin user interface client. (In addition, local connections are usually done through the Vtrin Server, as it allows for an additional protection layer for the database tables.)

The Engineering UI user interface connects the database using the services of the Vtrin Server as the very first step when the client is started. If the connection string begins with wss:// or `tcp://. Then the connection is done through the Vtrin Server.

Configuration

After installation, no configuration changes are required (or conditions where configuration changes are required should at least be very rare). Vtrin Server reads the configuration on startup from the file Vtrin-NetServer.exe.config, which is located in the same directory where Vtrin Server is started (Example: "C:\Program Files\ABB Oy\RTDB\Bin). The directory can be checked from the services.msc properties "Path to executable". This directory is a bit different depending on the operating system type (64 or 32 bit), or the type of RTDB installation (Data Collector or Main).

The configuration file is XML and contains, for example, details of what IP addresses and ports are used, what database to connect to, and what kind of buffer sizes and timeouts are available for different kinds of communication scenarios. The meaning of each parameter is briefly and quite technically described using XML comments.

Sometimes it is valuable to run the service interactively from the command line. This can be done by disabling the service from services.msc and stopping it. The command line can be copied from the services.msc properties "Path to executable", and adding -d to the end. For example:

"C:\Program Files\ABB Oy\RTDB\Bin\Vtrin-NetServer.exe" -d

Stopping the service is done by pressing the "ESC" button. Note that this is quite different to what is done for some other services that are stopped using Ctrl-C. For Vtrin-NetServer, this would violently terminate the program and potentially break database tables.

📘
For you changes to be applied, you need to manually rester "Vtrin Server" service on your system. On Windows, that can be done using Task Manager application.

Global configuration parameters

Parameter	Default Value	Meaning
AccountQueryFilter	Domain='%COMPUTERNAME%'	Win32_Account query WHERE clause - can be used for performance reasons to prevent Vtrin-NetServer from scanning the complete domain for users. (if the security editor seems to freeze, you need to tune this one). %COMPUTERNAME% is substituted with the name of the machine running the Vtrin Server.
AllowGuestLogin	false	(In 5.0 SR2 - see also directory configuration ) Enable to allow WebSocket access to server data sources without authentication.
AllowPlainTextPasswords	false	Enable to allow using authentication on non-secure (HTTP/WS) connections (very bad idea).
AlternativeServers	none	Information about redundant database servers. Value is the wss-based URI string, e.g. "wss://:/history".If there are more than one redundant servers, use comma to separate the servers, e.g."wss://:/history,wss://:/history"
ChangeSendDelay	500	Time to wait in ms when event is triggered for further events to combine them into a single frame, set to zero to disable (will disable lag, but cause a lot of TCP ping pong with any larger amounts of events).
CertificateName	Windows« vtrincert Linux (on 5.3 Q1/2025 and above)« vtrincert.pem	Friendly name of a certificate in the local machine / my certificate store to be used for HTTPS/WSS connections OR a filename of a file in PKCS12 (PFX) format that contains both public and private key and is protected by password 'vtrincert'. The file storage should not be used in production systems, it is currently provided in order to test .NET Core implementations that lack the certificate store.
CipherSuiteBlacklist		5.3 December 2023 and later only. Comma separated list name parts of the cipher suites that should not be used. E.g. "_AES_128_" prevents using any cipher suites using 128bit AES (containing _AES_128_ in their name). Do not put extra whitespace in the comma separated list. The names are case sensitive. In addition to this setting there this builtin blacklist in VtrinLib that cannot be modified (as of 2023-10-25): TLS_RSA_WITH_,TLS_PSK_WITH_,_ECDH_,_DH_,_DHE_,_anon_,_DES_,_DES40_,_RC4_,_3DES_,_IDEA_,_NULL_,_MD5,_CBC_ (However, you can enable some of them again by using CipherSuiteWhitelist)
CipherSuiteWhitelist		5.3 December 2023 and later only. Comma separated list of name parts of the cipher suites that should be enabled regardless of them being blacklisted either by CipherSuiteBlacklist setting or VtrinLib's internal blacklist. On Windows it is not possible to enable any ciphers that are not already enabled on OS level, on Linux you can. Do not put extra whitespace in he comma separated list. The names are case sensitive.
ConnectMessage		A message to display when user connects to the system. Can be used to display eg. a legal disclaimer or such.
Debug	false	Set to enable extra logging and dumping exception call stacks to clients.
DisableNativeConnectionStringJSHandling	false	Set to disable connectionstring.js handling under Vtrin Server, allowing use of IIS plugin to do the work.
DisablePersistAspxWrite	false	Set to disable the possibility to store View dashboards as .mdd files.
DoSBanExtendThreshold	10	These settings control Vtrin-NetServer's application level denial of service protection. If more than DoSBanThreshold connections are established to server from one IP address within the DoSGuardTimeSeconds then that IP address is banned for DoSBanTimeMinutes. If a banned IP address tries to establish more than DoSBanExtendThreshold connections within DoSGuardTimeSeconds average within the ban time, then the ban is extended by an additional DoSBanTimeMinutes. DoSExcludeLocalhost can be used to exclude the localhost from the ban processing (default behavior). Note that if some 3rd party software is used for forwarding connections to Vtrin-NetServer, then all connections might appear to be coming form localhost effectively rendering this protection useless.
DoSBanThreshold	500
DoSBanTimeMinutes	1
DoSExcludeLocalhost	true
DoSGuardTimeSeconds	15
EnableCertificateAuthentication	false	Set to enable authentication by client certificate (mutual authentication). Note: enabling is global and causes certificate to be requested even for directories the certificate authentication is disabled!
EnableKerberosAuthentication	true	(OBSOLETE in 5.0 SR2t) Enable to using Kerberos authentication. (On Windows only)
EnableOData	false	Enables the OData API endpoint.
EnableSSL2 (< 5.2)	false	Enable to allow using SSL2 encryption. Warning: SSL2 is known as vulnerable and should be avoided. No longer supported in 5.2 and later.
EnableSSL3 (< 5.2)	false	Enable to allow using SSL3 encryption. Warning: SSL3 is known as vulnerable and should be avoided. No longer supported in 5.2 and later.
EnableTLS1	false (was true in 510.1803.21230.93 and older)	Disable to ban the use of TLS 1.0 encryption.
EnableTLS1.1	true	Disable to ban the use of TLS 1.1 encryption.
EnableTLS1.2	true on Windows 8/2012 and newer	Disable to ban the use of TLS 1.2 encryption. (In Windows 2008, this should be set to false for the Vtrin 5.0 version so that the Vtrin Server will not try to use an unsupported protocol version, leading to the error "A call to SSPI failed" to the Vtrin Server log file, at least in the current (2017-08-30) version. Notice that starting from version 5.1, Vtrin no longer supports Windows 2008).
EnforceHTTPS	false	Enforce use of HTTPS by redirecting all HTTP connections.
ForwardHTTPConnectionsTo		Address to forward HTTP connections to, eg. http://localhost:81.
ForwardHTTPSConnectionsTo		Address to forward HTTPS connections to, eg. https://localhost:444.
Hostname	auto	Hostname to be used for unique naming of the datasources within this machine, use "auto" for autodetect. Autodetect will use NLB name automatically if only one NLB group is present.
LDAPServers		Comma separated list of fully qualified domain names of the domains that can be used for additional user authentication. (see LDAP authentication below for further info). Leave empty to disable.
LogFile		Name of the file to store diagnostic messages into, name (not the extension) will be suffixed with date and there will be one file for every day.
LogLength	30	Length of the diagnostic log in days.
LoginPageTitle	cpmPlus Login	[Forms Authentication] The title shown on the login page.
LoginPageCopyright		[Forms Authentication] The copyright text on the login page.
LoginPageDisclaimer	This is a private system. Do not attempt to logon unless you are an authorized user. Any authorized or unauthorized access and use may be monitored and can result in criminal or civil prosecution under applicable law.	[Forms Authentication] The disclaimer text on the login page.
LoginPageUsernameLabel	Username	[Forms Authentication] The username label text on the login page.
LoginPagePasswordLabel	Password	[Forms Authentication] The password label text on the login page.
LoginPageButtonLabel	Login	[Forms Authentication] The submit button text on the login page.
LoginPageLoginFailed	Authentication Failed. Wrong username or password.	[Forms Authentication] The error message for failed login attempt shown on the login page.
LoginPageCustomLogo		[Forms Authentication] The URL to a custom image shown in the top left corner of the login page. NOTE: It is advisable to install the image file in the login folder under the SourceRoot OR to a folder that has anonymous access enabled.
MaxConcurrentBackfillCommits	3	Maximum number of threads that can write backfill data to database in parallel.
MaxConcurrentBackfillRequestsPerSession	4	Maximum number of active backfill requests per session.
MaxConcurrentCallsPerSession	3	Maximum number of calls in concurrent execution for a single session.
MaxConcurrentSessionsPerUser	10	Maximum number of concurrent sessions for one user.
MaxConcurrentGuestSessions	20	Maximum number of concurrent sessions for non-authenticated users.
MaxRequestSize	32768	(Available in 5.3 2025/Q2+) Maximum http request size in bytes. Larger requests will lead in terminating the connection.
SendQueueLimit	512	Maximum number of outgoing frames to queue for a single client. If exceeded, the connection is automatically closed.
SessionCookieLifetimeSeconds	300	Time to keep the HTTP session cookie alive after the connection is closed. After session cookie is expired the authentication must be done again.
SourceRoot	view	The directory the WS/WSS connections are being served from (under the WWWRoot). To specify more than one alternative, use semicolon separated list (eg. "view;history").
UILogLengthDays	30	Length of the update log (UILog/UILogDetail classes).(version info: before version 5.0 that it was fixed to 30 days)
UseWin32InteractiveLogin	false	(Available in 5.2 SR1+) If enabled Vtrin Server will try to call win32 LogonUser-method with LOGON32_LOGON_INTERACTIVE -parameter in case the normal call with LOGON32_LOGON_NETWORK fails. This is generally not a good idea as it is network logon that you are actually making, but it allows use of local user accounts in systems that prevent network login (eg. ABB laptops).
WebSocketServerPort	80	Port to host HTTP/WS serving, set to zero to disable.
WebSocketServerSecurePort	443	Port to host HTTPS/WSS serving, set to zero to disable.
WebSocketHandshakeTimeoutMS	10000	Timeout during WebSocket handshake and web request processing. Keep low to make Denial Of Service attacks bit harder.
WebSocketReadTimeoutMS	600000	Timeout when waiting for commands from an established WebSocket connection.
WebSocketWriteTimeoutMS	30000	Timeout when writing results to an established WebSocket connection.
WWWRoot	Windows« c:inetpubwwwrootLinux« /srv/miaroot	The root directory of the HTTP/HTTPS serving.

*) The setting was datasource-specific in version 4.6 and older.

LDAP authentication (Windows only, 5.0.1 and above)

For cases where the server running the Vtrin Server process is not part of the same domain as the users accessing it, and there is no trust between the domains, you may specify a list of allowed user domains in the "LDAPServers" configuration entry. This makes it possible for users of foreign domains to log on to the system. The access control definitions of these users must be done using foreign domain groups/usernames. Please use the following checklist when setting up the LDAP authentication support:

The listed names must be fully qualified domain names (eg. not NMEA, but instead NMEA.abb.com).
The servers must be configured to support the secure socket layer.
The domain's secure socket layer certificate must be installed and/or trusted by the server running Vtrin Server.
The domain servers must be introduced either by DNS or the host file to the server running Vtrin Server.

The Secure Socket Layer support is required to prevent man-in-the-middle attacks, as well as introducing a malicious domain controller, together with DNS poisoning.

Datasource specific configuration parameters

For each datasource, the configuration must contain a set of entries starting with DataSource[n], where n is a number starting from zero and increasing by one for each of the datasources.

**Data Source Example **

This example defines wss://cpmplus.net/history as a secondary datasource (index [1]).

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <appSettings>
       <!-- Data sources under appSettings -->
       <add key="DataSource[1].Uri" value="cpmplus.net" /> <!-- friendly name -->
       <add key="DataSource[1].ServerDSN" value="wss://cpmplus.net/history" />
       <add key="DataSource[1].TimeZone" value="Europe/Helsinki" />
       <add key="DataSource[1].UserName" value="*VTRIN/wss://cpmplus.net/history" /> <!-- from credential storage -->
       <add key="DataSource[1].Password" value="" />
       <add key="DataSource[1].AdministratorGroup" value="\RTDB-admin" />

       <!-- continued... -->
    </appSettings>
    <!-- continued... -->
</configuration>

NOTE: Plain-text passwords should be avoided. It is recommended to store the data source user credentials in secure credential storage of the local server user account (the one that is running the Vtrin Server service). On Linux the credentials can be stored to cpmplus user using runcpm VtrinCmd:

$ runcpm VtrinCmd --connectionstring wss://cpmplus.net/history --user cpmvtest --savecredentials --acceptnewkeys Enter password for user cpmvtest:

'' * * * * * * * * * * * * * * * * *

Storing credentials to credential storage Enter vault name or press ENTER to use the default name VTRIN/wss://cpmplus.net/history:

Credentials stored as VTRIN/wss://cpmplus.net/history (--user "*VTRIN/wss://cpmplus.net/history")

(Here, cpmvtest is a user who can log in to wss://cpmplus.net/history.)

On Windows OS, the credentials can be similarly stored (with runcpm), but typically they need to be separately moved to the LOCAL SYSTEM account (or whichever account is running the Vtrin Server service).

VtrinCmd --connectionstring wss://cpmplus.net/history --user cpmvtest --savecredentials --acceptnewkeys

The credential vault entry can be transferred using APP_TransferVaultEntries.bat (included in the ABB Ability History installation).

%app_root%\Config\FeatureInstall\APP_TransferVaultEntries.bat /name VTRIN/wss://cpmplus.net/history

(This step is not necessary if the VtrinCmd command can be run as the Vtrin Server service user.)

Directory-specific setting under configuration/system.webServer

Directory-specific configuration is for the supported parts mostly compatible with Microsoft Internet Information Services (IIS). Directory-specific configuration is always inherited from the parent directory, except for the root directory, which inherits it from the master configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
   <system.webServer>
       <!-- Directory-specific settings here -->
   </system.webServer>
</configuration>

Custom headers

Custom headers can be used to specify additional HTTP headers that will be added to every HTTP response.

<configuration>
  <system.webServer>
    <httpProtocol>
      <customHeaders>
         <add name="X-Frame-Options" value="sameorigin" />
         <add name="X-Content-Type-Options" value="nosniff" />
         <add name="X-XSS-Protection" value="1;mode=block" />
         <add name="Strict-Transport-Security" value="max-age=63072000; includeSubDomains; preload" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Authentication (5.0 SR2 and above)

Directory content can be protected by requiring basic or Windows (kerberos) authentication. In order to use Windows authentication, the (obsolete) KerberosAuthentication parameter has to be set to true as well. AzureAD authentication is available from 5.1 release (builds after 15th June 2017). Certificate authentication is available from 5.1 release (builds after 21st July 2017). Forms authentication is available in History 5.2 - 2019 Q1 release (View release 1.6). All authentication methods are disabled by default. If multiple authentication methods are enabled at the same time, you might want to enforce the use of one, and you can do it by adding ?authtype=method_name (where method_name is anonymous/basic / certificate/forms/windows / azuread / identityserver / oauth2) in the URL.

<configuration>
	<system.webServer>
		<security>
			<authentication>
      	<!-- Use clear to remove inherited methods if you want. -->
        <clear/>
				<anonymousAuthentication enabled="false" />     
				<basicAuthentication enabled="true" />
        <certificateAuthentication enabled="true" />
        <formsAuthentication enabled="true" />
        <windowsAuthentication enabled="false" />
        <AzureADAuthentication enabled="true" tenant="abb.onmicrosoft.com" clientid="my_client_id" secret="my_secret" AzureADGroupType='NetBIOSDomain' />
        <!-- IdentityServer4 supported on 5.3 2022 Q1 and later. -->
        <IdentityServerAuthentication enabled="true" serveraddress="https://my_server" clientid="my_client_id" secret="my_secret"/>
        <!-- Generic OAuth2 supported on 5.3 2022 Q2 and later. -->
        <OAuth2Authentication enabled="true" openidconfiguration="https://my_server/my_path/.well-known/openid-configuration" clientid="my_client_id" secret="my_secret"/>
       </authentication>
    </security>
  </system.webServer>
</configuration>

Note: To ensure that you can retrieve groups that the user is a member of from Azure AD, you should grant the app registration at least the User rights. Read and Group.Read.All (latter needed for getting group names, for plain group ids it is not needed). If this cannot be achieved, you can also create an optional claim to include groups into tokens, but this only works as long as the user is a member of <=200 groups. The group format for AzureAD can be configured by the 'AzureADGroupType' optional configuration argument, which accepts values 'NetBIOSDomain' (DOMAIN\group, default), 'DNSDomain' (mydomain.com\group), 'Plain' (group) or 'IdOnly' (GUID). Versions earlier than 5.3 (August 2025) require groups as part of the token and will fail with >200 groups.

Authorization

Directory or file-specific access control can be done using authorisation rules to determine what resources users can or cannot access. If an authorisation rule is applied under the connectionStrings.data location, it will enforce the rule on database access and restrict user access to all directories, including vtrin. Therefore, it is advisable not to apply the rule at this path. Instead, it is recommended to apply the rule under the index.html location path.

The following is the parameter information that we use in the authorisation rule.

Parameter	Default Value	Meaning
DataSource[n].Uri
DataSource[n].ServerDSN		Connection string for the server-side driver.
DataSource[n].UserName		Username for Vtrin Server to logon to datasource - you should grant all required privileges for this user as Vtrin Server has its own authentication and security handling.
DataSource[n].Password		Password for VtrinServer to logon to datasource
DataSource[n].AdministratorGroup	Windows« BUILTINAdministratorsLinux« root	User or group, the members of which are allowed to bypass all security checks.
DataSource[n].RobotGroup	Windows« RobotsLinux« robots	User or group, the members of which will be excluded from logging changes to prevent flooding of the logs.
DataSource[n].TimeZone		Override to timezone setting, if not specified the server tries to detect the timezone from the operating system settings (which can be bit inaccurate in Windows as Windows does not contain proper timezone information itself).
DataSource[n].PGMPort	0	Legacy .NET Remoting only: PGM (Pragmatic General Multicast = reliable multicast protocol) port - 0 to disable - PGM Usage requires installing operating system PGM support for both client and server side. Current Windows versions require administrative privileges for programs that use PGM.
DataSource[n].PGMIP	234.231.x.x	Legacy .NET Remoting only: PGM address used for keeping clients up to date. Any x's in this address will be replaced with hashcode from the ServerDSN. In IPv6 environments, try FF0F:0:0:0:ABB:F1:x:x.
DataSource[n].PGMWindowSizeMs	30000	Legacy .NET Remoting only: PGM window size in milliseconds - note that when PGM is enabled, the memory usage will be PGMWindowSizeMs/1000*PGMRateKbps/8, so do not set too high.
DataSource[n].PGMRateKbps	8192	Legacy .NET Remoting only: PGM maximum transmission rate in kilobits per second.
DataSource[n].UDPMulticastPort	7609	Legacy .NET Remoting only: UDP Multicast port - 0 to disable.
DataSource[n].UDPMulticastIP	234.231.x.x	Legacy .NET Remoting only: UDP Multicast address used for keeping clients up to date. Any x's in this address will be replaced with hashcode from the ServerDSN. In IPv6 environments, try FF0F:0:0:0:ABB:F1:x:x.
DataSource[n].TCPEventTransportPort	0	Legacy .NET Remoting only: Set to non-zero to enable the use of a secondary TCP connection for transferring real time events.
DataSource[n].MulticastAdapterIPList		Legacy .NET Remoting only: List of network adapter IPs to use for multicasting - use ipconfig on command-line to obtain. Leave empty to use all available adapters.
DataSource[n].MulticastTimer	1000	Legacy .NET Remoting only: Multicast delay in ms when sending packets if data is available. May send faster if packets get filled faster.
DataSource[n].MulticastTimeToLive	1	Legacy .NET Remoting only: Multicast time to live - increase this to pass routers if required.
DataSource[n].MulticastReceiverTimeout	30000	Legacy .NET remoting only: Multicast timeout in ms for clients - if no multicast is received within this period, the client will ask data via the primary TCP/HTTP connection.
DataSource[n].MulticastMaxMessageSize	29440	Legacy .NET Remoting only: Multicast maximum message size. Setting it to a multiple of a standard Ethernet packet's usable size of 1472 is typically the most optimal. Note that UDP protocol does not support message sizes over 64kB. Messages larger than this will be transferred via the primary connection.
DataSource[n].MulticastMessageQueueSpan	60000	Legacy .NET Remoting only: Time to buffer sent multicast messages, so that clients can fetch them via TCP/HTTP.
DataSource[n].MulticastReceiveBufferSizeInKB	1024	Legacy .NET Remoting only: Size of the multicast receive buffer on the client side - make this larger if you are having a lot of events or experiencing packet loss on multicast.
DataSource[n].MulticastSendBufferSizeInKB	1024	Legacy .NET Remoting only: Size of the multicast send buffer on the server side - make this larger if you are having a lot of events.
DataSource[n].MulticastCompressionEnabled	true	Legacy .NET Remoting only: Specifies whether the multicast traffic should be compressed or not.

Parameter isRequired Datatype Description

accessType

Yes

enum

Defines allow or deny rule for the authorization.

Can be one of the following values (case insensitive):

Value	Description
Allow	Whitelist a specific user account or user group to access the directory/file.
Deny	Blacklisting a specific user account or user group from accessing the directory/file.

NOTE:

Deny rules are stronger than Allow rules.

We recommend configuring an "allow" rules instead of a "deny" rules. Allow rules grant access only to users in the specified role, while deny rules can sometimes lead to unintended access issues in certain scenarios.

role

string

Specifies the user group(s) or individual username(s) for the authorization rule. Multiple user groups can be added, in a comma-separated list.

The value is not case insensitive

Note:

If the user group has no associated domain just provide the user group.

On windows, usernames require a prefix indicating either computer name or domain name. On Linux, usernames do not require any prefix and can be provided directly.

verbs

string

Defines the HTTP methods for the authorization rule. Multiple HTTP methods can be added to a comma-separated list.

If the value is left blank or not defined, then by default it will apply to all HTTP methods.

NOTE:

Not yet implemented.

It is generally preferable to avoid using deny rules. However, if a deny rule must be enforced, it is recommended considering the use of individual usernames rather than entire user groups to maintain granular access control.

<configuration>
  <system.webServer>
    <security>
        <authorization>
            <clear/>
            <!-- Use clear to remove inherited methods if you want. -->
            <add accessType="allow" roles="role1" />
            <add accessType="allow" roles="role1,domain1\role2,\role3" />
            <!-- always checks the deny rules as a priority followed by allow rules. -->
            <add accessType="deny" roles="user1,domain1\user2,\user3" />
            <!-- if user1 is accessing the site but user1 is listed in the 
            authorization rule then access is denied by default -->
        </authorization>
    </security>
  </system.webServer>
</configuration>

Default document

If a folder contains a default document, it will be shown to the user instead of the directory listing. By default, only index.html is recognized as a default document, but you can add any file you want as a default document.

<configuration>
  <system.webServer>
    <defaultDocument>
      <files>
        <add value="Vtrin.Application" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

Directory browsing

If directory browsing is enabled, and no default document is present in the directory, Vtrin Server will generate a listing of the directory contents. Setting it to false will cause the "404 - Not Found" error to be presented instead.

<configuration>
  <system.webServer>
    <directoryBrowse enabled="false" />
  </system.webServer>
</configuration>

Enforce HTTPS (5.3 2025 Q1 and newer)

If enforce https is enabled, all http requests will just get redirected to https. This is a directory-specific setting; the old appSettings level EnforceHTTPS setting, if exists, gets overridden by this.

<configuration>
  <system.webServer>
    <enforceHTTPS enabled="true" />
  </system.webServer>
</configuration>

HTTP compression

The directory is currently ignored and a temp directory is used instead.

<configuration>
  <system.webServer>
    <httpCompression>
      <staticTypes>
        <add mimeType="text/*" enabled="true" />
        <add mimeType="message/*" enabled="true" />
        <add mimeType="application/javascript" enabled="true" />
        <add mimeType="*/*" enabled="false" />
      </staticTypes>
    </httpCompression>
    <urlCompression doStaticCompression="true" />
  </system.webServer>
</configuration>

HTTP logging (5.0 SR2 and above)

HTTP Requests logging can be enabled by specifying httpLogging element. The attribute dontLog can be used to disable the logging, while the selectiveLogging can be set to LogAll/LogSuccessful/LogError.

<configuration>
  <system.webServer>
     <httpLogging dontLog="false" selectiveLogging="LogError" />
  </system.webServer>
</configuration>

IP filtering

IP filtering can be used to allow/ban certain IP ranges. Both IPv4 and IPv6 are supported. The default behavior can be specified with the "allowUnlisted" parameter, and then a set of other rules can be applied on top. Note that, like other settings, this one is inherited from the parent and adding new rules will just append them to parent rules, unless you use the "clear" to clear the parent entries. It is also possible to remove existing entries with the "remove" keyword, and specifying the ipAdddress and subnetMask parameters.

<configuration>
  <system.webServer>
    <security>
      <ipSecurity allowUnlisted="false">
        <clear/>
        <add ipAddress="127.0.0.1" allowed="true"/>
        <add ipAddress="192.168.1.0" subnetMask="255.255.255.0" allowed="true"/>
      </ipSecurity>
    </security>
  </system.webServer>
</configuration>

Referrer control

Referrer control can be used to prevent embedding components of the site to other web sites. Completely clear list allows referring from anywhere, "auto" only from the same site. You can also whitelist any number of other sites, which are allowed to refer.

<configuration>
  <system.webServer>
     <security>
        <allowedReferrers>
           <clear/>                        <!-- Clear inherited settings -->
           <add value="auto"/>             <!-- Allow from the same site -->
           <add value="www.contoso.com"/>  <!-- Allow also from www.contoso.com -->
        </allowedReferrers>
     </security>
  </system.webServer>
</configuration>

MIME types

Files, for which MIME types are not recognised, are not allowed to be downloaded. Vtrin Server supports a large set of built-in mime types, but you can modify/clear the list in this section.

<configuration>
  <system.webServer>
    <staticContent>
      <remove fileExtension=".svg" />
      <mimeMap fileExtension=".svg" mimeType="image/svg+xml" />
      <remove fileExtension=".svgz" />
      <mimeMap fileExtension=".svgz" mimeType="image/svg+xml" />
      <remove fileExtension=".eot" />
      <mimeMap fileExtension=".eot" mimeType="application/vnd.ms-fontobject" />
      <remove fileExtension=".otf" />
      <mimeMap fileExtension=".otf" mimeType="font/otf" />
      <remove fileExtension=".woff" />
      <mimeMap fileExtension=".woff" mimeType="font/x-woff" />
    </staticContent>
  </system.webServer>
</configuration>

Connection forwarding

Query to certain URL can be forwarded to another URL using the following syntax:

<system.webServer>
  <rewrite>
     <rules>
        <rule name="ReverseProxyInboundRule1" enabled="true" stopProcessing="true">
           <match url="(.*)" />
           <action type="Rewrite" url="http://127.0.0.1:81/mypath/{R:1}" logRewrittenUrl="true" />
           <credentials username="myuser" password="mypassword" /> <!-- Credentials can be omitted, if not required -->
        </rule>
     </rules>
  </rewrite>
</system.webServer>

File specific configuration

It is possible to override the directory config for some specific file by using the following syntax:

<configuration>
   ...
   <location path="login.html">
      <system.webServer>
         <!-- Insert file specific configurations here -->
      </system.webServer>
   </location>
</configuration>

Legacy .NET remoting configuration

To enable legacy .NET remoting (tcp://) connection support, you must add the following configuration under the configuration section.

<system.runtime.remoting>
	<application>
		<service>
			<wellknown mode="Singleton" type="ABB.Vtrin.Drivers.cNetServer, VtrinLib" objectUri="MyVtrinDb.rem" />
		</service>
		<channels>
			<!-- Enable following channel section for normal TCP-connections, comment out if under IIS -->
			<channel ref="tcp server" port="7606" name="">
				<clientProviders>
					<provider type="ABB.Vtrin.cAdvancedClientSinkProvider, VtrinLib"/>
					<formatter ref="binary"/>
				</clientProviders>
				<serverProviders>
					<provider type="ABB.Vtrin.cAdvancedServerSinkProvider, VtrinLib"/>
					<formatter ref="binary" typeFilterLevel="Full"/>
				</serverProviders>
			</channel>
			<!-- Enable following channel section for kerberos TCP-connections, comment out if under IIS (Vtrin 4.x only) -->
			<channel ref="tcp server" port="7605" secure="true" name="" tokenImpersonationLevel="Identification" protectionLevel="None">
				<clientProviders>
					<provider type="ABB.Vtrin.cAdvancedClientSinkProvider, VtrinLib"/>
					<formatter ref="binary"/>
				</clientProviders>
				<serverProviders>
					<provider type="ABB.Vtrin.cAdvancedServerSinkProvider, VtrinLib"/>
					<formatter ref="binary" typeFilterLevel="Full"/>
				</serverProviders>
			</channel>
			<!-- Enable following channel section to provide http connectivity as standalone (without IIS) -->
			<!--
				<channel ref="http server" port="80" name="VtrinChannel">
				<clientProviders>
					<provider type="ABB.Vtrin.cAdvancedClientSinkProvider, VtrinLib"/>
					<formatter ref="binary"/>
				</clientProviders>
				<serverProviders>
					<provider type="ABB.Vtrin.cAdvancedServerSinkProvider, VtrinLib"/>
					<formatter ref="binary" typeFilterLevel="Full"/>
				</serverProviders>
			</channel>
			-->
			<!-- Enable following channel section to execute under IIS (see notes on top of file) -->
			<!--
			<channel ref="http" priority="100" name="VtrinChannel">
				<clientProviders>
					<provider type="ABB.Vtrin.cAdvancedClientSinkProvider, VtrinLib"/>
					<formatter ref="binary"/>
				</clientProviders>
				<serverProviders>
					<provider type="ABB.Vtrin.cAdvancedServerSinkProvider, VtrinLib"/>
					<formatter ref="binary" typeFilterLevel="Full"/>
				</serverProviders>
			</channel>	
			-->
		</channels>
	</application>
	<customErrors mode="off"/>	<!-- Custom Errors must be off or some error messages get crippled! -->
</system.runtime.remoting>

Vtrin trace switch names

Any application that uses VtrinLib can tune trace level with the following kind of settings in their .exe.config file:

<configuration>
  <system.diagnostics>
    <switches>
         <add name="ServerWebSocket" value="Verbose" />
         <add name="ClientWebSocket" value="Verbose" />      
    </switches>
  </system.diagnostics>
</configuration>

The available trace switch names are: ServerWebSocket, ClientWebSocket, MiaClient, DriverSkeleton, VtrinLib, PortForwarder.

The possible trace level values are: Off, Error, Warning, Info, Verbose, VeryVerbose (VeryVerbose is an extension used by Vtrinlib over the .NET standard trace levels). The default value for all switches is Info except for PortForwarder it is Warning.

For example, you can define the above settings to Vtrin-Netserver.exe.config file to tune the amount of trace to be printed to the Vtrin Server's log file. The Vtrin Server needs to be restarted to take the changes into use.

To define trace setting for Vtrin client program (Vtrin.exe) create Vtrin.exe.config file to the same directory as Vtrin.exe. Then you can run Vtrin with command line qualifier -debugtrace %temp%\vtrintrace.log to save the trace messages to log file (starting from version 5.1, the actual name of the log file also contains a date, such as %temp%\vtrintrace_2018-04-05.log).

Version info: The trace switches are available starting from 5.1 version (feature version 17.12).

Port forwarding

Vtrin Server includes port forwarding support to allow sharing the HTTP/HTTPS connections with another web server, and forwarding the connections of other services either to server ports or to selected clients.

While forwarding the HTTP/HTTPS connections adds a slight performance hit, it makes Vtrin Server compatible with all other web server implementations. This allows you to use Vtrin Server together with your favorite web server, while retaining full performance when communicating with its own clients.

Configuration

To enable port forwarding support, you need to modify the Vtrin Server configuration file.

<configuration>
	<appSettings>
                <!-- Forward incoming HTTP connections to localhost:81, excluding NetServer WebSocket connections -->
		<add key="ForwardHTTPConnectionsTo" value="http://localhost:81" />
                <!-- Forward incoming HTTPS connections to localhost:444, excluding NetServer WebSocket connections -->
		<add key="ForwardHTTPSConnectionsTo" value="https://localhost:444" /> 
                <!-- Allow client sessions owned by members of MYDOMAIN\Administrators to use port forwarding to 10.11.12.13:3379, while suggesting 33333 as the client side port -->
		<add key="ClientTunnel[0]" value="MYDOMAIN\Administrators@33333 to 10.11.12.14:3389" />  
                <!-- Allow client sessions owned by members of MYDOMAIN\Administrators to use port forwarding to 10.11.12.13:22, while suggesting 33334 as the client side port -->
		<add key="ClientTunnel[1]" value="MYDOMAIN\Administrators@33334 to 10.11.12.14:22" />  
                <!-- Allow client sessions owned by members of MYDOMAIN\Administrators to use port forwarding to map the server port 33335, while suggesting www.mydomain.com:443 as the target on the client side -->
		<add key="ClientTunnel[2]" value="MYDOMAIN\Administrators@33335 from www.mydomain.com:443" />  
                <!-- Allow client sessions owned by members of MYDOMAIN\Administrators to use port forwarding to map the server port 33336, while suggesting https://www.mydomain.com:443 as the target on the client side and removing the https encryption -->
		<add key="ClientTunnel[3]" value="MYDOMAIN\Administrators@http://localhost:33336 from https://www.mydomain.com:443" />  
                <!-- Forward SERVER's port 7777 to 10.11.12.13:3379 -->
		<add key="ServerTunnel[0]" value="7777 to 10.11.12.13:3389" />  
                <!-- Forward SERVER's port 7778 to 10.11.12.13:22 -->
		<add key="ServerTunnel[1]" value="7778 to 10.11.12.13:22" />  
	</appSettings>
</configuration>

Details

When forwarding HTTP or HTTPS connections, Vtrin Server needs to change the host field of the HTTP headers. To make it possible for the server to detect the forwarding, it also adds a custom header X-Forwarded-From, which contains the address the request was originally made from. All other connections (not HTTP/HTTPS) are forwarded intact.

Security notice

Forwarding HTTPS connections requires Vtrin Server to act as a man-in-the-middle and decrypt the messages, as tampering with the "host" header field is required. This should not be an issue if the forward target is on the same machine. However, if you plan to gateway the connections to another server, you need to be aware that if the Vtrin Server node is compromised, monitoring / tampering with the forwarded data is possible.

Diagnostics

Logging is done to the folder %APP_DATAPATH%\diag\. Log files are named by combining "Vtrin Server" with the date when the log information has been generated, e.g. Vtrin Server_2011-12-31. The content of the file can be verbose, and it also contains a lot of low-level information that can be valuable in troubleshooting situations for the developers and for customer support. For the administrator of the system, the information usually does not tell very much.

Using Vtrin Server from 3rd party code

Although there are ready-made APIs for accessing Vtrin-NetServer functionality from C# (VtrinLib), JavaScript (View) and C++ (Device SDK), there might sometimes be cases when you want to access the functionality directly either with your own or some 3rd party code. In order to accomplish this, you have a couple of options regarding the connectivity and serialization. Use of a WebSocket connection is highly recommended whenever possible, as it provides by far the most efficient way to communicate with the server and also the ability to use binary serialization for even better performance and type safety. Regardless of this, it might sometimes be convenient to use plain HTTP connectivity, especially if you are debugging or you are using a third party application that lacks WebSocket support, and you are only going to make a couple of calls to the server.

Available Connection Types

The following table summarizes the available connection types and serializers:

Connection Type	JSON	Binary
Websocket	✓	✓
HTTP POST (REST)	✓
HTTP GET with URL-parameters	✓

All connection types support both secure (https/wss) and unsecure (http/ws) connections, depending on the Vtrin Server Configuration.

WebSocket

WebSocket connections can be done with any standard WebSocket library compliant with RFC 6455. All text frames are expected to contain JSON serialized commands and all binary frames are expected to contain binary serialized commands. The server will reply to JSON serialized commands with JSON, and to binary serialized commands with binary, so it is also possible to mix the JSON and binary serialization within a single connection. As WebSocket is a true full duplex transport, any subscribed values will arrive immediately as soon as the server has sent them.

HTTP

With plain HTTP connectivity, you can only use JSON serialization. Since HTTP connections are not persistent, your session is lost whenever the connection is terminated, unless your application supports cookies. In this case, your session stays alive for an additional 90 seconds, during which you can even reconnect and continue. This naturally has no effect on cases where all the commands you are executing are stateless by their nature. The JSON serialized connections can be sent to the server as a body of a HTTP POST or as URL parameter (execute=...), and the server will then reply with a JSON serialized message. In case there are active subscriptions that the server has new data to be sent, this data will not automatically get to the client. Only if the client makes some other call, the server will bundle the subscribed data together with the actual reply of the call. The body of the POST can either be plain JSON or URL-encoded, in which case the request must have a Content-Type header with the value of "application/x-www-form-urlencoded".

Call Structure

Regardless of the communication and serialization method, the call structure is always the same. In a single message, there can either be a single command or multiple commands combined together. When sending multiple commands to the server in separate messages, the server runs the commands in parallel. When multiple commands are combined into a single message, they are executed sequentially. There are two types of commands: function executes and pushes. Both of these commands start similarly with the client-specified call id, but differ after that. The function executes provide a way to asynchronously execute parametrized commands on the server, while getting a return value back. Pushes provide an efficient way to produce data to the server without getting a return value back. Both pushes and method executes can be combined into the same message. The client can freely select a 64bit (52 bit on JSON) positive value for the call id that is used in the calls, but the client has to make sure that there are never two identical ids existing at the same time. As JavaScript does not support 64bit integers, the value is serialized as double instead, leading to an effective precision of only 52 bits.

A single command is presented as an array. When combining multiple commands into the same message, the single commands are combined as an array, resulting in an array of arrays. Arrays are used instead of name-value collections to maximize the performance, as JSON specification does not guarantee the order of the name-value pairs in the serialization process. This enforces the server to fully deserialize the message before executing it, while arrays are guaranteed to retain their order, making it possible to start the execution of the command immediately.

Function Calls

Index	Name	Description
0	Call Id	A 64bit (52bit on JSON) call id the client can freely select
1	Function Name	Name of the function to execute
2	Parameters	Array of function parameters

**Pushes **

Index	Name	Description
0	Call Id	A 64bit (52bit on JSON) push subscription id
1	Push data	An array containing the pushed data

**Function Call Reply **

Index	Name	Description
0	Call Id	Call Id as it was on success, negated on failure
1	Return Value	Function return value on success, exception message (string) on failure

Examples

The following examples are in JSON, but the exact same data can be serialized as binary as well. For the full API documentation, please refer to ABB Ability(TM) History View documentation.

Getting Time From Server Call:

[1,"GetServerTimeInUTCFromServer",\[]]

Server reply:

[1,"14815255832914531"]

List Currently Connected Users Call:

[1,"FetchClassData",\["ServerUser",["UserName"],-1,"ORDER BY UserName"]]

Server reply:

[1,{"Data":["COM600-PC\\COM600","COM600-PC\\COM600","COM600-PC\\Demo","COM600-PC\\Ilpo"],"Truncated":false}]

Error in Call Parameters Call, which contains "error" in a parameter that should contain an integer value:

[1,"FetchClassData",\["ServerUser",["UserName"],"error"]]

Server replies with negated call id (-1 instead of 1) and error message:

[-1,"System.Runtime.Serialization.SerializationException,mscorlib: Invalid string '\"error\"]]' to decode as a Int32 starting from position 47."]

Combining Get Server Time and Get Connected Users Together Call:

[\[1,"GetServerTimeInUTCFromServer",\[]],\[2,"FetchClassData",\["ServerUser",["UserName"],-1,"ORDER BY UserName"]]]

Server reply:

[[1,"14815267524747434"],\[2,{"Data":["COM600-PC\\COM600","COM600-PC\\COM600","COM600-PC\\Demo","COM600-PC\\Ilpo"],"Truncated":false}]

Getting Server Time via URL Parameter Type to URL of your browser:

https://localhost/view/connectionstring.data?execute=[1,"GetServerTimeInUTCFromServer",[]]

Body of the reply from server:

[1,"14815255832914531"]

Updated 2 months ago