Install a MID Server on Windows

Install MID Servers with the MID Server guided Windows installation package. The package includes an installer that automatically configures OpenJDK to run in the environment. The MID Server can use an existing JRE rather than the provided OpenJDK. Uninstall the MID Server to redeploy it.

• Verify that the host computer satisfies the MID Server system requirements.
• The MID Server requires the minimum PowerShell version 3.0 and supports versions up to PowerShell 5.1.
• Ensure that the Microsoft Application Experience Lookup Service is enabled on the MID Server host. If this service is disabled, the MID Server auto-upgrade might fail, causing the MID Server to go down. For information on managing issues with the Application Experience service, see KB0597552.

Java 11.0.17 is bundled with the MID Server installer package and is installed on the host for all new MID Servers. The installer automatically configures Java 11.0.17 to run in your environment. No additional configuration is required. This version supports both 64-bit Windows MID Servers and 64-bit Linux MID Servers. The MID Server requires a minimum JRE version 11.0.8, and recommended version 11.0.17. If you are using a lower version than 11.0.8, you may see encryption related issues.

Note:

ServiceNow no longer supports new installations of 32-bit MID Servers or upgrades to version Rome. New MID Server installation are blocked through RPM and MSI installer on the following operating systems:

• CentOS 7
• Windows server 2008
• Windows server 2008 R2
• Windows 8
• Windows 10

MID Servers can be manually installed to any operating system with the ZIP file, however Windows 10 is unsupported. Unsupported MID Servers auto-upgrading to Rome create an issue record in MID Server Issues (ecc_agent_issue). For more information, see Supported platform changes for MID Server [KB0863694].

Testing showed that the MID Server works as expected with Oracle Java 11 version 11.0.5. If you need to upgrade the JRE to a different version, then coordinate with the appropriate account representative for support.

Upgraded MID Servers might use different Java versions depending on their operating system versions.

• MID Servers upgraded from earlier versions use the OpenJDK provided with the MID Server installer. This version of the OpenJDK was tested and certified for use with these MID Servers.
• MID Servers upgraded on any other operating system versions also automatically upgrade the JRE to the version provided with the installation package.

Install a MID Server on Windows with guided installation

Install MID Servers with the MID Server guided Windows installation package. The package includes an installer that automatically configures OpenJDK to run in the environment.

Before you begin

Role required: admin or mid_server

About this task

The MID Server guided native Windows installer will configure the MID Server with provided settings. The installer creates the MID Server Service and assigns it to the provided user. The installer sets the file permissions on the MID Server Install folder. The installer allows for the configuration of proxy settings. Optionally, the installer can start the MID Server automatically.

Procedure

1. On the instance, download the MID Server installation .msi file from MID Server > Download.
2. Log in to the Windows host machine where you want to install the MID Server.
3. Place the installer .msi on the desired MID Server host.
4. Open the installer with Administrator level privileges.
5. Use the installer to enter the following information.

   

   Field	Description
   Authentication Type	Basic Username and password based authentication. Mutual Client certificate based authentication. See MID Server unified key store for more information on mutual authentication. Note: Selecting mutual authentication disables the MID Server username and password fields. The disabled fields are not written to config.xml.
   ServiceNow instance URL	Enter the full URL of your instance, for example: https://mycompanyinstace.service-now.com
   ServiceNow MID Server username	Enter the name of the MID Server user that you already created. The MID Server user must have the mid_server role.
   ServiceNow MID Server password	Enter the password for the user in the ServiceNow MID Server username.
   Certificate Revocation	This check box is selected by default to enable certificate revocation policies to improve security. For more information on certificate revocation, see MID Server certificate check policies. When testing a connection with certificate revocation enabled, the installer checks if OCSP port 80 is open and the entrust page is accessible. If the connection test fails due to the certificate revocation check, the error must either be corrected and re-tested or the certificate revocation check must be disabled. The certificate revocation check is not required for successful installation.
   Use proxy	Select this check box if your MID Server communicates through a proxy to connect to the instance. Note: Your proxy server must use Basic Authentication for the MID server to connect to the instance. The MID Server can bypass proxy servers whose DNS/IP address is listed in the configuration parameter mid.cloud.discovery.proxy.exclusion.list. See MID Server property for more information.
   Proxy host	Enter the proxy server host name or IP address. Do not include the protocol in the host name. For example, enter proxyserver.domain.com, not https://proxyserver.domain.com.
   Proxy port	Enter the port through which the proxy server communicates. If you leave this field blank, it should use the proxy server's default port number.
   Proxy username	Enter the user name that has administrator rights to the proxy server.
   Proxy password	Enter the password for the user name.

6. Click Test your connection to validate the credentials and instance information.
   If you encounter any errors, verify the information that you input.
7. Click Next.
8. Configure the MID Server name and Service Account parameters (see table).

   

   Field	Description
   MID Server name	Enter a MID Server name. Warning: MID Server names cannot begin with mid.server.
   Service Account Name	Username of the service account that will be used to run the MID Server service. For information on creating service accounts, see Create a Windows service account with "Log on as Service" [KB0867669]. Service Account Name field is an editable drop-down menu. Either select a value from the drop-down or type a new value in the text field. Only the accounts with log on as service policy are displayed in the drop-down. Group Managed Service Accounts (gMSA) that inherit the log on as service policy from their groups are not displayed in the drop-down. However, you can install the MID Server service using those accounts by manually entering the service account name in the editable drop-down. The name can follow three formats. If the service account is local to the computer, you can give just the name. Example: My_Local_Service_Account If the service account is local to the computer, you can provide “.” as the domain name for the account. Example: .\My_Local_Service_Account Any account can follow the format {domain}\{username}. Example: MY-COMPUTER-DOMAIN\My_Domain_Service_Account Add a new local service account by selecting the + button. This button opens the Configure New Local User window, which has three fields. Service Account Name: Enter the name of the new service account. Service Account Password: Enter the password of the new service account. Re-enter Password: Confirm the password of the new service account. When a group Managed Service Account (gMSA) user is selected, the password field is removed because passwords for gMSA users are managed by the Active Directory. Note: The provided service account credentials must meet the following requirements in addition to being a valid account. The user cannot be a local system or an administrator level account (local admin, domain admin, etc.) The service account provided has the log on as service right, which is required for an account to be used as the log on user for a service.
   Service Account Password	Password of the service account that will be used to run the MID Server service.
   Set Service Name Manually	Select this check box if you want to manual set the service name and display name for your MID Server. Note: Your proxy server must use Basic Authentication for the MID server to connect to the instance.
   MID Service wrapper name	Modify this field if necessary. It is populated automatically by prefixing snc_mid_ to the MID Server name. In most cases, you do not need to modify this.
   MID Server wrapper display name	Modify this field if necessary. It is populated automatically by prefixing ServiceNow MID Server_ to the MID Server name. In most cases, you do not need to modify this.

9. Click Next and select a destination folder for the installation.

   Users can manually enter an existing, valid file path, or use the “Change” button to open up a browsing page where they can choose the install location.

10. Click Next to view the summary.

    

    Select Start MID Server after installation if you want to start the MID Server immediately after installation. If you wish to make additional configuration changes, before starting the MID server, leave this box unchecked. If mutual authentication was selected, the MID Server username and password fields are removed.

    Note:

    If the MID Server fails to start, the cause might be a duplicate name or multiple services that point to the same executable path. This can happen when you have MID servers previously not installed through the installer. See MID Server fails to start for details.
11. Click Mid Servers List Page.
    The installer opens the MID Server list from your instance.
12. Select the MID Server name from the list.
    Note:

    It may take a few seconds for the MID Server time to establish a connection with your instance.
    The system displays the MID Server record.
13. From Related Links, click Validate.
    The MID Server Validated changes to Yes.

What to do next

To upgrade the MID Server, see MID Server upgrades for procedures and requirements.

Uninstall a Windows MID Server with the guided installer

The MID Server guided native Windows installer also supports guided uninstallation of the MID Server.

Before you begin

Role required: admin

There are three ways to uninstall a MID Server after installing it with the guided native Windows installer.

Procedure

1. On the MID Server host, navigate to the Control Panel > Programs > Programs and Features > Uninstall a program.
   1. Uninstall the program with the MID Server's name.
2. Optional: Alternatively, navigate to Settings > Apps
   1. Uninstall the program with the MID Server's name.
3. Optional: The MID Server can also be uninstalled with the silent uninstall script.
   This is useful for uninstalling multiple MID Servers. For more information, see Windows MID Server silent installation and uninstallation

Configure Windows MID Server service credentials

MID Server service credentials are required to manage the MID Server service on the host machine, including its ability to successfully auto-upgrade.

Before you begin

Role required: admin

About this task

If you installed the MID Server using the native installer, you will not need to complete this procedure. However, to change the service user after the installation for any reason, use this procedure.

Windows service credentials control the level of privilege on the device. The user should not be a local system or an administrator level account (local admin, domain admin, etc.) The service account provided should have the log on as service right, which is a requirement for an account to be used as the log on user for a service.

Note:

Windows service credentials are not the same as the MID Server user credentials, which allow communication between the MID Server and the instance. You must configure both of these credentials separately. See Create the MID Server user and grant the role for instructions on MID Server user credentials.

Procedure

1. Open the Windows Services console.
2. Double-click the ServiceNow <MID Server name> service for each MID Server.
3. Select the Log On tab.
4. Choose a non-admin user and provide the password for that user.
5. In the General tab, set the Startup type.
   The field is set to Automatic by default.
6. Click OK.
7. Restart the ServiceNow <MID Server name> service, and make sure that ServiceNow\<MID Server name>\agent\logs\agent0.log does not have error messages.
   If the MID Server does not start, see the ServiceNow knowledge article Review the agent log for MID Server errors (article KB0535148).
8. On the instance to which this MID Server is connected, navigate to MID Server > Servers.

   If Discovery is installed, alternately navigate to Discovery > MID Servers. All MID Servers connected to this instance are listed.

9. Make sure that the Status of the MID Server that you just installed is Up.

Windows MID Server silent installation and uninstallation

Silently installing the MID Server uses predefined parameters and requires no user input after it is initiated. You can use silent installation on several machines at once to quickly set up a network and to ensure all MID Servers have the same installation settings.

MID Server silent installation

Note:

All silent install/uninstall commands must be run with administrator level privileges.

To silently install the MID Server on a Windows system, download the script attached to the Knowledge Base article Windows MID Server silent installation and uninstallation. Place the file on the target MID Server host machine and run the following command from the command prompt. You can also run the script directly from powershell.

powershell -command “.\SilentInstall.ps1 -<parameter_name1> ‘<value for parameter1>’ -<parameter_name2> ‘<value for parameter2>’ etc…”

The script checks the following mandatory parameters:

• MSI_FILE_NAME: the name of the MSI file used for the installation.
• INSTALL_LOCATION : the location to install the MID Server.
• INSTANCE_URL: the target ServiceNow instance the MID Server will connect to.
• MID_USERNAME: the instance account name.
• MID_PASSWORD: the instance account password.
• MID_NAME: the name of the MID Server.
• SERVICE_ACCOUNT_NAME: the name of the service account.
• SERVICE_ACCOUNT_PASSWORD: the password of the service account.

The following parameters are optional:

• LOG_NAME: enables logging and puts logs into the file named by this parameter.
• START_MID: sets the MID Server to start automatically after the installation finishes.
• USE_PROXY: enables the use of a proxy. If you choose this command, the following parameters become mandatory.
  • PROXY_HOST: the name of the proxy host.
  • PROXY_PORT: the port number of the proxy.
  • PROXY_USERNAME: the proxy username. If there is no username, input ‘’.
  • PROXY_PASSWORD: the proxy password. If there is no password, input ‘’.
• MANUAL_SERVICE_NAME: the service name. If you choose this command, the following parameters become mandatory:
  • SERVICE_NAME: the service name.
  • SERVICE_DISPLAY_NAME: the service display name.
• MUTUAL_AUTH: enables mutual authentication. If this switch is enabled, MID_USERNAME and MID_PASSWORD are not required. See MID Server unified key store for more information.

Note:

The parameters START_MID, USE_PROXY, MUTUAL_AUTH, and MANUAL_SERVICE_NAME are switches. They use the format -<switch_param_name> and are not followed by a value.

After the script runs, verify the MID Server files, service, and entry in Programs and Features are installed. If you enabled logging, verify the log info in the file specified by the LOG_NAME parameter.

An example MID Server silent installation command:

powershell -command ".\SilentInstall.ps1 -MSI_FILE_NAME 'MID-Installer.msi' -INSTALL_LOCATION 'C:\Users\Administrator' -INSTANCE_URL 'https://my-instance-name.service-now.com' -MID_USERNAME 'mid_server' -MID_PASSWORD 'mid_password' -MID_NAME 'Silent_Install_MID' -SERVICE_ACCOUNT_NAME 'DOMAIN\My_Service_Account' -SERVICE_ACCOUNT_PASSWORD 'Service_Account_Password' -LOG_NAME 'Silent_Install_Log.txt'"

An example command using the START_MID switch:

powershell -command ".\SilentInstall.ps1 -MSI_FILE_NAME 'MID-Installer-Wix.msi' -INSTALL_LOCATION 'C:\Users\Administrator' -INSTANCE_URL 'https://my-instance-name.service-now.com' -MID_USERNAME 'DOMAIN\My_Service_Account' -MID_PASSWORD 'mid_password' -MID_NAME 'Silent_Install_MID' -SERVICE_ACCOUNT_NAME 'DOMAIN\My_Service_Account’ -SERVICE_ACCOUNT_PASSWORD 'Service_Account_Password' -LOG_NAME 'Silent_Install_Log.txt' -START_MID"

MID Server silent uninstallation

To silently uninstall the MID Server on a Windows system, download the script attached to the Knowledge Base article Windows MID Server silent installation and uninstallation. Then run the script using the command prompt. It can also be run directly from powershell.

powershell -command “.\SilentUninstall.ps1 -MID_NAME ‘<value for MID_NAME>’ -LOG_NAME ‘<value for LOG_NAME>’”

The script requires the mandatory parameter MID_NAME, which is the name of the MID Server you want to uninstall.

The optional parameter LOG_NAME enables logging of the uninstallation and puts logs into the file named by this parameter.

After the script runs, verify the MID Server files, service, and entry in Programs and Features are uninstalled. If you enabled logging, verify the log info in the file specified by the LOG_NAME parameter.

An example MID Server silent uninstall command:

powershell -command ".\SilentUninstall.ps1 -MID_NAME 'silent_install_cmd' -LOG_NAME
      'uninstall.txt'"

Manually install a MID Server on Windows

Install MID Servers with the ZIP file installation package and verify it is active.

Before you begin

Role required: admin or mid_server

About this task

Click this link to view the installation video:

Procedure

1. Log in to the Windows host machine where you want to install the MID Server.
2. Create a folder for the MID Server on the top level of the drive such as ServiceNow\MID Server1.
3. Download the MID archive file into the new folder.
4. Right-click the archive and select Extract All.
5. Navigate to the service-now\<mid server name>\agent folder that was created when the file was extracted.
6. To configure the MID Server manually, edit the config.xml file with a text editor such as WordPad:
   1. Find the element <parameter name="url" value="https://YOUR_INSTANCE.service-now.com" /> element and change the value to the URL of your instance.
   2. Enter the MID user credentials in the mid.instance.username and mid.instance.password parameters.
      By default, the MID Server, uses basic authentication for SOAP messages. The password value is also encrypted authentication.
   3. Optional: Find the <parameter name="name" value="YOUR_MIDSERVER_NAME_GOES_HERE" /> element and change the value for the MID Server name.
   4. Optional: Enter connection information for the proxy server.
      Remove the appropriate comment tags from the proxy configuration information.
      For example, you can configure these parameters:

      • mid.proxy.use_proxy
      • mid.proxy.host
      • mid.proxy.port
      • mid.proxy.username
      • mid.proxy.password
7. Run start.bat to start the MID Server.
8. On the instance, in the Related Links, select Validate.
   The MID Server Validated changes to Yes.

Run a Windows MID Server as a non-admin after manual installation

MID Servers can be configured to run using non-administrative accounts. Using non-admin accounts in conjunction with file permission enforcement can improve security by restricting access to MID Server files.

Before you begin

Role required: admin

Note:

In a future release, non-admin accounts will be mandatory for the MID Server, and support for using an administrative account will be deprecated.

This procedure is only for users who install the MID Server using the ZIP file. The Windows MID Server installer already requires the MID Server run as a non-admin user. As part of the MID Server installer's installation process, the access control lists for the MID Server folder are restricted to the following users and groups.

• System
• Administrator
• The configured service account

When installing using the ZIP file, install the MID Server on a Windows machine using an administrator account. Create a Windows user account without administrative privileges.

Running a MID Server with a non-admin account has limitations and changes the behavior of other applications. The following behavior changes can occur:

• The MID Server account needs appropriate credentials to run a Discovery schedule. If the credentials are insufficient, the MID Server falls back to the user account's privileges. A non-admin user account may not have the necessary privileges to access the Discovery target.
• Enhanced Application Dependency Mapping (ADME) and File Based Discovery (FBD) may not work by default. To correct this issue, non-admin users need to be given permission to read/write to the Admin Share folder.
• Non-admin accounts cannot initiate upgrade services in versions prior to the Orlando release.

Procedure

1. Run the MID Server service as LocalSystem or as a user with admin rights.
2. Create a file entitled GrantStartStopPerm.ps1 with the following code.

   Function GrantStartStopPerm
   {
       Param( [string]$username, [string]$servicename )
       $user = New-Object System.Security.Principal.NTAccount($username) 
       $sid = $user.Translate([System.Security.Principal.SecurityIdentifier]).Value 
       Write-Output "Sid : $sid"
   
       $sd = sc.exe sdshow $servicename
       Write-Output "SD value   : $sd"
                      
       if( !($sd -like "*$sid*") ){
           $permsToAdd = [string]::Format(")(A;;RPWPCR;;;{0})S:(", $sid);
           if($sd -match [regex]::Escape(")S:(")){
               $sd = $sd -replace [regex]::Escape(")S:("),"$permsToAdd"
               $result = sc.exe sdset $servicename $sd
               Write-Output "SD changed : $sd";
               Write-Output "Result : $result";
           }
       }else{
           Write-Output "Sid is already part of SD"
       }
   }

3. Start the PowerShell console as an administrator.
4. Load the file by using the dot-source function from the GrantStartStopPerm.ps1 file.
   For example: C:\Users\mid_account\Desktop> . .\GrantStartStopPerm.ps1
5. Run PowerShell sourced function with non-admin account and the service name as input.
   For example:

   GrantStartStopPerm mid_account snc_mid_test
   Output line expection in success :
   Result : [SC] SetServiceObjectSecurity SUCCESS

6. Add the non-admin account name to the MID Server parameter mid.windows_host.file_permissions.allow_list in the MID Server host's config.xml file.
   This step adds the non-admin account to the allow list. See MID Server parameters for more information about mid.windows_host.file_permissions.allow_list as well as instructions for adding a parameter to the config.xml file.
7. Restart the MID Server.
   The new file permission enforcement rules take effect when the MID Server starts.
8. Switch the MID Server to the non-admin service account.
9. Restart the MID Server.

What to do next

For more information about managing the allow list and file permission enforcement, see File permission enforcement for Windows MID Servers.

Uninstall a Windows MID Server after manual installation

The MID Server runs as a stand-alone service. You can remove a stand-alone MID Server service to accommodate such tasks as redeploying the MID Server to another host machine or changing the unique name of a MID Server when deploying multiple MID Servers.

Before you begin

Role required: admin

This procedure is only for users who install the MID Server using the ZIP file.

Procedure

1. Stop the running MID Server service, using either of these procedures:
   • Windows command line: From the MID Server home (agent) directory, run stop.bat.
   • Windows Services console: From the Windows Services console, right-click the ServiceNow MID Server name and then select stop.
2. From a command prompt, go to the \agent\bin directory in the MID Server installation directory and double-click the UninstallMID-NT.bat file.

What to do next

Validate the MID Server to prepare it for use.

Configure a MID Server on Windows to use an existing JRE

You can choose to use an existing JRE for your MID Server rather than the OpenJDK provided with the MID Server installer.

Before you begin

Ensure that your JRE version is supported. See MID Server system requirements for details.

Role required: admin

About this task

By electing to use your own JRE, you are responsible for upgrading it as necessary. For a detailed procedure and cautions regarding changing the JRE, see KB0778272.

Procedure

1. Navigate to this file in the MID Server installation directory:
   agent/conf/wrapper-override.conf
2. To specify the existing Java executable that you want to use, add this line to the file:
   wrapper.java.command={your_java_executable}

   For more information, see the Java service wrapper property documentation.

3. Save the file.