ServiceNow MID Server: Installation, Configuration, and Troubleshooting

The MID Server is one of those components that works silently in the background — until it doesn't. When discovery fails, orchestration breaks, or your cloud integration stops polling, the first thing you check is the MID Server. Yet most ServiceNow administrators treat it as a black box. This guide pulls back the curtain.

What a MID Server Actually Does

A ServiceNow MID Server is a Java application that runs on your infrastructure (on-prem or cloud VM) and acts as a bidirectional proxy between your ServiceNow instance and systems that can't be reached directly from the internet. The instance initiates outbound HTTPS connections to the MID Server — the MID Server then reaches out to targets on your private networks using protocols that browsers can't: SSH, WMI, SNMP, JDBC, WinRM, and more.

The key architectural point: the MID Server never receives inbound connections from ServiceNow. It polls the instance every few seconds over HTTPS. If the instance can't reach the MID Server's poll endpoint, the MID appears offline in the instance's MID Server list — even if the process is running fine on your end.

Installation on Windows

Prerequisites

• Windows Server 2016 or later (2022 recommended)
• 4 vCPU minimum, 8GB RAM recommended for production
• Java 17 runtime (OpenJDK or Eclipse Temurin — NOT the Oracle JDK download page, use Eclipse Adoptium)
• Network access to your ServiceNow instance on port 443
• Outbound access to target systems you'll be probing
• A dedicated service account with network access and read permissions on targets

Installation Steps

1. Download the MID Server JAR from your ServiceNow instance: MID Server → Downloads → Windows Installation Package
2. Create the installation directory — e.g., C:\ServiceNow\mid
3. Grant the service account full control on the installation directory and all subfolders
4. Run the installer as an administrator: java -jar sncqmid.jar
5. Provide your ServiceNow instance URL (e.g., https://yourinstance.service-now.com), the MID Server name, and credentials for a MID Server user
6. Install as a Windows service — say yes when prompted, this allows the MID to start on boot without a logged-in user
7. Verify — the MID should appear in MID Server → Servers within 30-60 seconds of startup

Critical Post-Install: Java Options

On Windows, after installation, edit $servicenow_home/bin/wrapper.conf. The default JVM heap settings are often too small for production workloads:

# Increase max heap to 2GB (adjust based on your workloads)
wrapper.java.maxmemory=2048

# Enable GC logging for troubleshooting
wrapper.java.additional.3=-XX:+UseG1GC
wrapper.java.additional.4=-Xlog:gc*:file=../../logs/gc.log:time:filecount=5,filesize=10M

Installation on Linux

Prerequisites

• RHEL 8/9, Ubuntu 22.04 LTS, or Debian 12
• Java 17 runtime (OpenJDK 17)
• 4 vCPU, 8GB RAM minimum
• systemd service account setup

Installation Steps

1. Download the Linux MID Server JAR from the instance
2. Create the directory: mkdir -p /opt/servicenow/mid
3. Extract or place the JAR in the directory
4. Create a dedicated user: useradd -r -d /opt/servicenow/mid -s /sbin/nologin miduser
5. Grant ownership: chown -R miduser:miduser /opt/servicenow/mid
6. Make the installer executable and run: chmod +x sncqmid.jar && java -jar sncqmid.jar
7. Follow the interactive prompts — instance URL, MID name, credentials

systemd Service for Auto-Start

Create /etc/systemd/system/mid_server.service:

[Unit]
Description=ServiceNow MID Server
After=network.target

[Service]
Type=simple
User=miduser
Group=miduser
WorkingDirectory=/opt/servicenow/mid
ExecStart=/usr/bin/java -jar /opt/servicenow/mid/agent.jar
Restart=on-failure
RestartSec=30
StandardOutput=append:/opt/servicenow/mid/logs/mid.out
StandardError=append:/opt/servicenow/mid/logs/mid.err

[Install]
WantedBy=multi-user.target

Then enable and start:

systemctl daemon-reload
systemctl enable mid_server
systemctl start mid_server
systemctl status mid_server

Configuring Probes and ECC Queue

The MID Server communicates with the instance primarily through the ECC (Enterprise Component Cache) queue. Probes are requests the instance sends to the MID Server; responses come back via the same channel.

Key MID Server Parameters

In the MID Server configuration (MID Server → Servers → select your MID → Parameters):

• mid.instance.url — your instance FQDN, must be reachable from the MID Server on 443
• mid.instance.poll_interval — how often the MID checks in (default 30 seconds, reduce to 10s for time-sensitive orchestration)
• mid.instance.proxy_url — if behind a proxy
• mid.service_account.name / mid.service_account.password — the MID user credentials
• extension.classes — additional Java classes for custom probes

Viewing the ECC Queue

As an admin: System Diagnostics → ECC Queue. You'll see entries with:

• Agent — the MID Server that should process this
• Queue — typically input for inbound probes, output for responses
• State — queued, ready, processing, processed

Stuck entries in input that never move to processing typically mean the MID isn't picking them up. Check the MID's connection and the ECC queue agent assignment.

Troubleshooting Connectivity Issues

MID Shows as Down But Service Is Running

1. Check the MID log at $servicenow_home/logs/mid.log. Look for connection errors, SSL handshake failures, or authentication rejections.
2. Verify HTTPS reachability from the MID Server: curl -v https://yourinstance.service-now.com
3. Check the instance's allowed IP ranges (MID Server → Installation Properties or the instance security settings)
4. Confirm the MID user is active in the instance and has the mid_server role

SSL Certificate Errors

Java's certificate validation is strict. If your instance uses a corporate PKI certificate:

1. Import the root CA certificate into the MID Server's Java truststore:
   Bash

   $JAVA_HOME/bin/keytool -importcert -trustcacerts \
     -alias your-ca -file /path/to/root-ca.pem \
     -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
   
2. Restart the MID Server service after importing

MID Server Reaches Instance But Discovery Still Fails

• Verify the target credentials are correct (Test Credential in Discovery)
• Check that the MID Server has network access to the target on required ports
• Look at the specific probe's log in $servicenow_home/logs/probe_<probetype>.log
• For WMI targets on Windows, the MID Server's service account needs DCOM remote access permissions

MID Server Eating CPU or Memory

1. Check how many parallel jobs are configured: ecc_agent.threads.max parameter (default 10, increase carefully)
2. Reduce concurrent probes in Discovery schedule configuration
3. Increase JVM heap (wrapper.java.maxmemory) and restart
4. Check for runaway probes — some custom probes can loop infinitely if the target responds unexpectedly

Automating MID Server Health Checks

Add this to your operational playbook with a scheduled script that runs via the MID Server's shell capability:

#!/bin/bash
# mid_health_check.sh - run via MID Server shell capability
MID_HOME="/opt/servicenow/mid"
LOG="$MID_HOME/logs/mid.log"
INSTANCE_URL="https://yourinstance.service-now.com"

# Check if process is alive
if ! pgrep -f "agent.jar" > /dev/null; then
  echo "ALERT: MID Server process not running"
  exit 1
fi

# Check disk space (warn if > 80%)
DISK_USAGE=$(df -h "$MID_HOME" | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "$DISK_USAGE" -gt 80 ]; then
  echo "WARNING: Disk usage at ${DISK_USAGE}%"
fi

# Check log rotation (warn if mid.log > 500MB)
LOG_SIZE=$(stat -c%s "$LOG" 2>/dev/null || echo 0)
if [ "$LOG_SIZE" -gt 524288000 ]; then
  echo "WARNING: mid.log exceeds 500MB"
fi

# Test instance connectivity
if curl -s --connect-timeout 10 "$INSTANCE_URL" > /dev/null; then
  echo "OK: Instance reachable"
else
  echo "ALERT: Cannot reach instance"
fi

Run this via a MID Server shell capability in a ServiceNow Orchestration workflow, or via cron on the host.

Multi-MID Server Architecture

For larger deployments:

• Use multiple MID Servers for discovery parallelism — one MID can't run more than a handful of probes concurrently
• Segment by network zone — put MID Servers close to the targets they need to reach (DMZ MID for cloud targets, internal MID for on-prem)
• Separate discovery from orchestration — use different MID pools so heavy discovery scans don't block time-sensitive orchestration workflows
• Load balancing — ServiceNow round-robins between available MID Servers in the same pool for the same agent type

Summary

The MID Server is infrastructure as much as it is a ServiceNow component. Treat it accordingly:

• Dedicated host per MID — don't share with other production workloads
• Monitor proactively — disk, memory, CPU, and log rotation
• Separate pools for discovery vs. orchestration — don't let one monopolize the other
• Keep Java and MID version current — stay within two releases of the instance version
• Test failover — stop the MID, verify the instance correctly marks it down, bring it back

A well-maintained MID Server infrastructure means discovery completes on schedule, orchestration runs reliably, and integrations don't silently drop. It's not glamorous, but it's essential.