A ServiceNow MID Server is a Java service that runs inside your network and carries out work the cloud instance cannot do directly, such as Discovery probes, LDAP imports, and calls to internal REST or database endpoints. This guide covers MID Server installation, the configuration that matters, and how to troubleshoot one that is down or slow.
How a MID Server communicates
The MID Server polls the instance over HTTPS on port 443. It picks up work from the ECC queue (ecc_queue table) as output records, runs the probe or command locally, and posts the results back as input records.
Every connection starts from the MID Server. The instance never calls into your network, which is why the firewall team only needs to allow outbound traffic to https://<instance>.service-now.com.
Before you install
- Host: a dedicated Windows or Linux server. Check the current system requirements for your release. As a starting point, plan for 4 CPU cores, 8 GB of memory, and 40 GB of disk.
- Network: outbound 443 to the instance, plus access from the host to the targets it will reach.
- Time: the host clock must be accurate. Clock drift causes authentication and certificate errors.
- MID Server user: create a dedicated user on the instance and assign the
mid_serverrole. Do not use a personal account or an admin account. - Service account: on Windows, the service should run as a domain account with the rights Discovery needs on its targets, not as Local System.
Install the MID Server
- On the instance, go to MID Server > Downloads and download the installer for your operating system. Use the installer from the same instance you will connect to, so the versions match.
- Run the installer on the host. On Windows this is an MSI. On Linux, install the package or extract the archive into a path such as
/servicenow/<mid-server-name>. - When prompted, enter the instance URL, the MID Server user name and password, and a unique MID Server name.
- Start the service.
- On the instance, open MID Server > Servers. The new record appears with Validated set to No. Open it and select Validate.
A MID Server does no work until it is validated. Validation also encrypts the password stored on the host.
One host can run several MID Servers. Install each one in its own folder with its own service name.
Key configuration
Settings live in config.xml in the agent folder, and most can also be set as Configuration Parameters on the MID Server record.
| Parameter | Purpose |
|---|---|
url | The instance URL |
mid.instance.username / mid.instance.password | The MID Server user credentials |
name | The MID Server name shown on the instance |
mid.proxy.use_proxy, mid.proxy.host, mid.proxy.port | Send instance traffic through a web proxy |
threads.max | Number of worker threads for standard-priority jobs |
Restart the service after you edit config.xml.
Memory is set separately, in agent/conf/wrapper-override.conf:
wrapper.java.maxmemory=2048
Raise this when the MID Server runs large Discovery schedules or big JDBC imports and the log reports out-of-memory errors.
Capabilities, applications, and IP ranges
The instance chooses a MID Server for each job using three settings on the MID Server record:
- Supported applications, such as Discovery, Orchestration, or ALL
- Capabilities, such as SSH, WMI, SNMP, or PowerShell
- IP ranges the MID Server may reach
If a Discovery schedule reports that no MID Server is available, the usual cause is a mismatch here. A MID Server limited to 10.10.0.0/16 will never be picked for a target in 10.20.0.0/16.
Clusters
Group MID Servers with the same capabilities into a cluster. A failover cluster moves work to the next MID Server when one goes down. A load balance cluster spreads work across all members. Use at least two MID Servers per environment.
Troubleshoot a MID Server
Start with the logs
On the host, open the agent/logs folder:
agent0.log.0is the main log. Search it forSEVEREandWARNING.wrapper.logrecords service start and stop events and JVM errors.
On the instance, check MID Server > Server Issues for problems the MID Server has reported about itself.
The MID Server is Down
Work through these in order:
- Is the service running on the host? Start it and watch
wrapper.log. - Can the host reach the instance? From the host, open the instance URL in a browser or run
curl -I https://<instance>.service-now.com. - Is the MID Server user active and not locked out on the instance? The active locked-out users report finds locked accounts quickly.
- Did the password change? Update
mid.instance.passwordinconfig.xmlwith the new plain-text value and restart. The MID Server encrypts it again on start. - Does
agent0.log.0show a certificate error? A TLS-inspecting proxy presents its own certificate, which the MID Server does not trust by default. Ask the network team to exclude the instance URL from inspection, or import the proxy's root certificate following the MID Server certificate documentation.
The MID Server is Up but jobs do not finish
Check the ECC queue. This background script, which only reads data, shows how much work is waiting per MID Server:
var queue = new GlideAggregate('ecc_queue');
queue.addQuery('queue', 'output');
queue.addQuery('state', 'ready');
queue.addAggregate('COUNT');
queue.groupBy('agent');
queue.query();
while (queue.next()) {
gs.info(queue.getValue('agent') + ': ' +
queue.getAggregate('COUNT') + ' output records waiting');
}
A large and growing count means the MID Server cannot keep up. Add a MID Server to the cluster, stagger Discovery schedules, or raise threads.max if the host has spare CPU and memory.
Output records stuck in Processing for a long time usually point to a probe that hangs on an unreachable target. The matching entry in agent0.log.0 names the target.
Credential failures
Discovery and Orchestration credentials are stored on the instance and sent to the MID Server when needed. When a probe fails to authenticate:
- Use Test credential on the credential record and select the MID Server that will run the job.
- Confirm the credential is not restricted to a different MID Server.
- For Windows targets, confirm the service account has the required rights on the target and that the firewall allows WMI or WinRM.
After an instance upgrade
MID Servers upgrade themselves to match the instance. If one stays on the old version, check that the host can download the package, that the service account can write to the agent folder, and that disk space is available. Then restart the service and review agent0.log.0. Add this check to your upgrade checklist.
Checklist
- Dedicated host with an accurate clock
- Dedicated user with only the
mid_serverrole - Outbound 443 allowed to the instance, with TLS inspection excluded
- MID Server validated
- Applications, capabilities, and IP ranges match the work it should do
- At least two MID Servers in a cluster per environment
- Logs and the ECC queue checked after every upgrade
Most integrations that run through a MID Server are REST or import jobs. The outbound REST integration guide and the import set best practices cover what to build on top of it.