Service Host Administrator Guide
Version 1.3 | Published August 14, 2019 ©
Control Mode
The Control Mode plug-in is registered as a Windows Service when the Service Host is installed. This service is the administration point for this Service Host. The shortcut to the Control Mode of the current Service Host can be found at %ProgramData%/vizrt/ServiceHost/ServiceHost.control. It provides the following functionalities via REST and Command interface.
This page contains information on the following topics:
On the welcome page, the first thing to do is to log in. The login name is used to log all interactions with the Control Mode. The login name can be viewed on the upper right of the GUI, next to the Login/Logout button.
Viz Engine
The Control Mode is aware of Viz Engine instances on the local machine. They can be controlled from here.
Follow the menu Monitor > Viz Engine.
to go to this screen.
Start a Viz Engine Instance
From the Viz Engine Instances Monitor page, the context menu on an individual Viz Engine instance or use the action bar on the bottom of the screen can be used to start Viz Engine instances.
The page is automatically refreshed every five seconds by default.
Preconditions
-
The Viz Engine needs to be installed at the default location.
Postconditions
-
Start: A Viz Engine was launched without GUI and without a console.
-
Start: The launch may have failed. Please check the reason in the logs. Context menu Logs or Menu Report > Logs > Viz Engine.
Stop a Viz Engine Instance
From the Viz Engine Instances Monitor page, the context menu on an individual Viz Engine instance or use the action bar on the bottom of the screen can be used to stop Viz Engine instances.
The page is automatically refreshed every five seconds by default.
Preconditions
-
Viz Engine needs to be installed at the default location.
-
The General Comm. Port of each Viz Engine instances need to be configured properly. Otherwise, the control instance will not be able to stop the specified Viz Engine instance correctly.
Postconditions
-
Stop: The Viz Engine instance was sent the EXIT command.
The shutdown of a Viz Engine may take some time. To kill the process, with all consequences, use Terminate from the context menu.
View Viz Engine Configuration
The config file of a Viz Engine instance can be viewed either from the Context menu on the Monitor page or via menu Configuration > Viz Engine.
From there, select the Viz Engine instance.
The page is view only.
View Viz Engine Logs
The log file of a Viz Engine instance can be viewed either from the Context menu on the Monitor page or via menu Report > Logs > Viz Engine.
From there, select the Viz Engine instance to filter the available log files and how many lines to display.
Notes
If Viz Engine is not installed on the machine, Service Host will show no installation at the status page.
And no instances are shown in the Monitor Viz Engine page.
Plug-ins
Register a Plug-in Instance
To register a new instance of a plug-in as a Windows Service, use the menu Configuration > Plug-in > Register New Instance.
On the following screen, select the plug-in type and give the instance a service and display name (e.g. register a Channel Recorder):
New Plugin Instance Success Dialog
Confirm by clicking Yes. The dialog moves directly to the configuration of this plug-in instance.
Configure a Plug-in Instance
The configuration of a plug-in instance can be reached from the Monitor plug-in page via the context menu of a plug-in instance or via the menu Configuration > Plug-in > Configure Instance.
Plug-in Monitor
The plug-in monitor page can be reached via the menu Monitor > Plug-in or from the welcome page by clicking on the Plug-in instances icon.
On this page, there is a filter on the left-hand side to select the available plug-in instances. Each concrete entry on the right-hand side has a context menu that allows the plug-in instance to be unregistered.
Start/Stop a Plug-in Instance
The context menu provides the capability to start/stop a plug-in instance.
Unregister a Plug-in Instance
The context menu provides the capability to unregister a plug-in instance. Once selected and the following dialog has been answered with Yes, then the plug-in instance is stopped if it was running and unregistered from Windows services.
Any log and configuration files remain in %ProgramData% for later use by a subsequent new registration.
Unregister a Plugin Instance
Report/Logs
The logs can be reached either via the context menu on the plug-in monitor page or from the menu Report > Logs > Plug-in.
On the left-hand side, there is the instance filter and the content of the selected log file is displayed on the right-hand side of the screen. The number of lines displayed can be selected. It operates like the tail command.
Notes
The Configuration File of a Plug-in Instance is Missing
The configuration file of a plug-in instance, located at %ProgramData%\vizrt\ServiceHost, contains the plug-in name, which is a most important information. Service Host uses the plug-in name to load the correct DLL at run time to serve functionalities and get some information from the DLL, such as the configuration model. If the configuration file missing, a plug-in instance cannot be started.
At the Plug-in monitor page, for the plug-in instances which their configuration files missing, the Plug-in field will be empty. To fix the problem, users need to unregister and re-register them.
Service Host (Control Mode)
The Control Mode can be configured too. For security reasons, the configuration of the Control Mode needs to be configured by administrators.
Configuration
The configuration page for the Control Mode may be reached via the menu Configuration > Service Host.
On this page, the REST listening address can be configured. By default, Service Host is listening to all interfaces. This is specified by [All interfaces] in the Listen to field. As port number, any valid and unused port number may be used. Later versions may support automatically finding of an available port number.
The Access Treat Type controls who is able to interact with the Service Host.
-
Only local access (LOCAL_ONLY): To allow only users accessing the GUI via the local machine to change the system (such register/unregister new plug-in instance or start/stop Viz Engine instances). Users accessing the GUI from external machine, regardless of whether authenticated, are not allowed to make any changes.
-
Authentication required (AUTHENTICATION_REQUIRED): Same as above, only local access; except that users accessing externally are allowed as long as they are authenticated. In future versions, this may change to all users are required to authenticate before they can make changes to the system.
-
No authentication (NO_AUTHENTICATION): No restrictions apply. All users may change the system, both locally and externally. We do no recommend this setting since there is no way of gathering user information in the operating logs.
The Arguments editor allows passing arbitrary startup arguments to the control mode plug-in. In this case, we set the log level to debug mode.
Allowed values for Arguments are:
-
-l debug
-
-l info
-
-l warning
-
-l error
-
-l off
Report/Logs
The logs produced by the control mode may be accessed via the menu Report > Logs > Service Host.
On the left-hand side, select the log file to be displayed. There are two types of logs available.
The Control Mode Log
This log file is named ServiceHost.control.log, it does log rotation and may also be reached via the log panel on the bottom of the screen.
and
Service Host Startup Logs
Logs are produced during startup and kept as long as this Service Host is running, so possible startup issues can be captured before a plug-in is loaded and initialized. These log files are removed after a successful shutdown. They are named ServiceHost.dateandtime.pid.log, where dateandtime is the date and time the selected timezone, pid is the process ID.
Debugging of Service Host
Manual Register/Unregister and Stop/Start
Service Host is capable of registering and unregistering itself as Control Mode service. This might be useful in cases not covered by the installer.
Z:\> ServiceHost.exe -c -i Z:\> ServiceHost.exe -c -rThe Service Host in Control Mode can also be started and stopped from the command line.
Z:\> ServiceHost.exe -c -s Z:\> ServiceHost.exe -c -kLaunch Service Host in Foreground with a Console Window
For debugging, the Service Host can be launched in foreground and with a console window attached. To list all the possibilities use the command line switch -h.
Z:\>ServiceHost.exe -hUsage:$0 [-v] ... start from within windows services, optional verbose mode$0 [-v] -N service_name -i ... install $service_name as service -v ... optional verbose mode$0 [-v] -N service_name -r ... remove $service_name as service -v ... optional verbose mode$0 [-v] -N service_name -s ... start service $service_name -v ... optional verbose mode$0 [-v] -N service_name -k ... kill service $service_name -v ... optional verbose mode$0 [-v] -N service_name -d ... run $service_name in debug mode with a console window -v ... optional verbose mode$0 [-v] -c -i ... install control as service, the service name is '{ProductName}.control' -v ... optional verbose mode$0 [-v] -c -r ... remove control as service, the service name is '{ProductName}.control' -v ... optional verbose mode$0 [-v] -c -s ... start control service, the service name is '{ProductName}.control' -v ... optional verbose mode$0 [-v] -c -k ... kill control service, the service name is '{ProductName}.control' -v ... optional verbose mode$0 [-v] -c -d ... run control in debug mode with a console window -v ... optional verbose mode-p "[argument...]" ... arguments that gets forwarded to the plug-in e.g. -p "-l debug -v"What we are interested in here are the lines with the -d option.
To start the Service Host in the Control Mode with a console window, make sure it is not running as windows service then launch it with -c -d options.
Z:\>ServiceHost.exe -c -kZ:\>ServiceHost.exe -c -dOptionally, you can add verbose and log parameters to the Service Host and the Control Mode plug-in.
Z:\>ServiceHost.exe -c -d -v -l debug -p "-v -l debug"the first -v -l debug are for the Service Host executable and the one inside the -p option are forwarded to the Control Mode plug-in. In the console mode, the logs are also forwarded to the console window.