Browse Month

February 2019

MID Server Installation

Introduction

Management, Instrumentation and Discovery Server (MID Server) form an interface between ServiceNow and e.g. data sources in internal company networks. The MID Server acts as a proxy to forward commands to locations that cannot be reached from the Internet. Typical use cases for MID servers are e.g. the execution of Discovery in the company’s own network, the execution of PowerShell scripts or the connection of internal sources for data import or export. The term MID Server refers to a service (Windows or Unix) and can easily be misunderstood because of servers. It is possible that several MID Servers (services) share the same virtual or dedicated server. A MID Server is therefore nothing more than a Windows or Unix Service running in the background.

Installation

In order for a MID Server to be able to log on to the ServiceNow instance, a corresponding user is required. Several MID Servers can share the same user. The communication with the MID Server takes place via SOAP. The user must therefore be assigned the role mid_server. This role inherits the role soap, which contains all roles relevant for communication and automatically assigns them to the user.

A separate agent must be created for each MID Server. The agent contains all files necessary for operation, including their directory structure. The installation files can be downloaded in the ServiceNow instance under the application MID Server > Downloads. After downloading and unpacking the files into a separate folder on the server (VM, dedicated, etc.), there are two options for setup.

For manual configuration, the files .\config.xml and .\conf\wrapper-override.conf must be adapted. The config.xml contains parameters such as MID Server Name, ServiceNow Instance, MID Server User and Password (for logging on to the instance) and other optional parameters that must or can be specified depending on the intended use. In the wrapper-override.conf a different name can be assigned to the Windows Service. This is mandatory if there must be several MID Servers on the same OS. For this the parameters wrapper.name (unique for all Windows Services) and wrapper.displayname must be defined. The wrapper service describes the Windows Service in whose context the respective MID Server is executed. For each additional MID Server a separate wrapper service with a unique name is required. A – in my opinion – particularly big pitfall is the format in which the .\conf\wrapper-override.conf is stored. The file must be saved in UTF-8 format, which is also shown in the file header. When the file is edited and saved with Notepad, the format changes to Unicode or ANSI, compromising the file. This may lead to a license error and can be fixed by explicitly saving the file in UTF-8 format using Save As. If the MID Server is run with .\start.bat, the wrapper service is started at the same time. If the MID Server is terminated with .\stop.bat, it should be noted that the wrapper service is still active. The Windows Wrapper Service can be completely removed using .\bin\UninstallMID-NT.bat if the MID Server is no longer needed.

With automatic configuration the setup is done via .\installer.bat in the root directory of the respective MID Server. The user interface then requests all mandatory information required for setup. The corresponding configuration files are then adapted automatically. I won’t describe this part any further, simply because I didn’t do it.

In both cases the MID Server is started at the end of the installation by .\start.bat, whereby the service logs on to the ServiceNow instance and creates an entry in the ecc_agent with the name specified in the .\config.xml. All parameters defined in the .\config.xml are displayed. Additionally there is the possibility to define further parameters, which are then automatically created in the .\config.xml. If the configuration was successful and the MID Server could log on to the instance, it must be validated. This is done via the UI Action Form link “validate”. This ensures that only authorized MID Servers are coupled with the respective instance. If the MID Server is validated, capabilities must be assigned to it. These determine which functions can be executed via the MID Server. For example, the Capability PowerShell is assigned for the execution of PowerShell scripts. The application, the capabilities and IP Ranges form the criteria that are searched for during Orchestration or Discovery. For example, if a MID Server meets the criteria expected from a Custom Workflow Activity, then the MID Server is used for the task. If no MID Server fulfills the required criteria, the standard MID Server is used which is stored in the Property mid.server.rba_default.

COPY AN EXISTING MID SERVER CONFIGURATION

Please note the following when copying the folder of an existing MID Server to start an additional Service:

The contents of the folder .\keystore must be deleted or the contained file must be renamed. The log files in the .\logs folder must be deleted. The passwords contained in the config.xml must be stored in plain text so that they can be encrypted automatically when .\start.bat is executed. Each MID Server Service has its own key for encrypting and decrypting the passwords from the .\config.xml file. The .\conf\wrapper-override.conf file must be edited and the service name and description must be unique compared to the existing MID Server Services. Once the points are done, the copied MID Server can be started.

Troubleshooting

Troubleshooting, e.g. if the MID Server Service is not started and does not log on to the instance, can be done via the log files in the folder .\logs. The same log files can also be retrieved via UI Action “Grab Logs” and analyzed in ServiceNow itself, if there is a connection to the MID server.

Auto Upgrade

In the standard system, a check is carried out hourly to see whether there is a new MID Server version. If that’s the case, it is installed automatically. The Auto Upgrade function is useful when the ServiceNow instance is upgraded. Because then, the version of the MID Server is automatically kept in sync with the version of the instance, ensuring compatibility. However, it is also possible to set the version of the MID Server of an instance to a specific version and to disable the upgrade function. Here, a property with the name mid.version.override and the corresponding version is created on the instance. This property is then valid for all MID Server Services. It is also possible to link only individual MID Server Services to a certain version by defining the parameter mid.pinned.version in the config.xml and setting it to a certain version.

Performance

There are a lot of additional parameters for config.xml that control the behavior of the MID Server. Of greater interest, also in terms of performance, is the parameter threads.max, which specifies the maximum number of threads that can be executed in parallel and is particularly important for discovery applications. Another parameter is #wrapper.java.maxmemory=1024 in the .\conf\wrapper-override.conf whose value specifies the maximum memory usage. If the number of threads is increased, the memory value should also be increased. Otherwise, the memory may be full before the thread maximum has been reached.

ECC Queue

If the MID Server is set up and ready for operation, communication takes place via the ECC Queue [ecc_queue]. Each request or response to/from the MID Server is processed in XML format. Each entry has a “Queue” field that specifies whether it is an incoming (input) or outgoing (output) payload. The “Response to” field, which is relevant for “Queue = Input”, states that it is the response to a previously sent request (output). For instance, if a PowerShell command was executed via the MID Server, the payload would be “Queue = Output” for the command to be executed and the response would reference tis request in its “Response to” field, and would have the output of the PowerShell command in its payload.

References

[1] https://docs.servicenow.com/bundle/kingston-servicenow-platform/page/product/mid-server/reference/r_MIDServerCapabilities.html

[2] https://docs.servicenow.com/bundle/kingston-release-notes/page/product/mid-server/concept/mid-server-upgrade-info.html

[3] https://docs.servicenow.com/bundle/kingston-servicenow-platform/page/product/mid-server/reference/mid-server-parameters.html

[4] https://community.servicenow.com/community?id=community_blog&sys_id=9d1deea5dbd0dbc01dcaf3231f961939