Monitor Your RingQ Server with SNMP
Monitoring lets your own SNMP monitoring tool watch your RingQ server around the clock. Your tool reads live numbers such as calls up now, phones registered, SIP trunks up, callers waiting in queues, free recording disk and whether RingQ Call Services is running, and can alert you before your users notice a problem. It uses SNMPv3 with sign-in and encryption, and only the addresses you allow can ask the server for numbers.
Before you start
- You are signed in as the Owner of the RingQ system. Monitoring is not shown to other roles.
- Your RingQ server is a dedicated server (self-hosted, on-premise or a dedicated cloud server). On shared, multi-tenant servers SNMP is not offered.
- You know the public IPv4 address of your monitoring tool (the address its polls come from).
- Your monitoring tool supports SNMPv3 with authentication and encryption (authPriv). Almost every current SNMP monitoring tool does.
Step 1: Open Monitoring
In the RingQ web app, go to Global Settings, scroll to Troubleshooting and open the Monitoring tile. Monitoring is off until you switch it on, so nothing on the server changes until you save.
If the page says the server is not ready for Monitoring yet, press Update in Global Settings, wait for the update to finish, then open Monitoring again.
Step 2: Choose who can poll
Under Who can poll, add the address of each monitoring tool that should read this server. You can add a name next to each address, such as Head office monitor, so you remember what it is.
| You can enter | Example | Notes |
|---|---|---|
| One IPv4 address | 203.0.113.25 | Most common: your monitoring server. |
| An address range | 203.0.113.0/28 | Ranges from /16 to /32. RingQ stores the network address. |
| Up to 20 entries | Each address or range counts as one entry. |
RingQ opens UDP port 161 for these addresses only. Every other address is refused, even if it knows the password. The rule survives restarts and works alongside the RingQ firewall and SIP Guard, and it is removed when you switch Monitoring off.
Step 3: Set the sign-in details
Your monitoring tool signs in to the server with a username, a password and an encryption key.
| Field | What to enter |
|---|---|
| Username | Defaults to ringq-monitor. Letters, numbers, dots, dashes and underscores, 3 to 32 characters. |
| Password | 8 to 64 characters, with no spaces, quotes or backslashes. Used to sign every poll. |
| Encryption key | Same rules as the password, and it must be different from the password. Used to encrypt the numbers. |
RingQ never shows the password or encryption key again after you save. Store them in your password manager. To change them, type new ones and save; your monitoring tool then needs the new values too.
Step 4: Switch Monitoring on and save
Switch Monitoring on and press Save. Within about a minute the status at the top of the page shows the server is ready. Until your tool polls for the first time, it shows Waiting for a poll.
The status tiles show:
| Tile | Meaning |
|---|---|
| Status | Working when polls are being answered, Waiting for a poll when none has arrived yet, or Off. |
| Allowed addresses | How many addresses or ranges may poll the server. |
| Polls today | How many polls the server has answered today. |
Step 5: Add the server to your monitoring tool
In your monitoring tool, add a new SNMP device with these settings:
| Setting | Value |
|---|---|
| Address | Your RingQ server name, for example pbx.example.com, or its public IP |
| Port | UDP 161 |
| SNMP version | SNMPv3 |
| Security level | authPriv (authentication and privacy) |
| Username | The username from Step 3 (ringq-monitor by default) |
| Authentication | SHA-256 (or SHA if you chose it under Advanced), with the password from Step 3 |
| Privacy / encryption | AES-128 (often shown as AES), with the encryption key from Step 3 |
Then press Download MIB on the Monitoring page and import the RINGQ-MIB file into your tool, so it shows readable names like ringqActiveCalls instead of numbers. You can also download the OID list as a spreadsheet if your tool asks for OIDs one by one.
If a firewall or cloud security group sits in front of your RingQ server, allow UDP 161 from your monitoring tool's address there as well.
Step 6: Test the connection
The Monitoring page shows a ready-made test command for your server. From the monitoring machine, a test with the standard snmpwalk command looks like this:
snmpwalk -v3 -l authPriv -u ringq-monitor -a SHA-256 -A 'your-password' -x AES -X 'your-encryption-key' pbx.example.com .1.3.6.1.4.1.8072.9999.9999.7746
A working setup lists the RingQ values below. Check Recent polls on the Monitoring page: it shows every poll from the last 24 hours with the address it came from and whether it was Answered or Refused.
Some older SNMP tools do not support SHA-256. If your tool cannot use SHA-256, open Advanced, choose SHA as the sign-in method, type the password and encryption key again and save.
What your tool can read
All RingQ values sit under the base OID .1.3.6.1.4.1.8072.9999.9999.7746. Numbers update once a minute.
| OID (after the base) | Name | What it is |
|---|---|---|
| 1.1.0 | ringqActiveCalls | Calls up on the server now |
| 1.2.0 | ringqCallsToday | Calls since midnight, server time |
| 1.3.0 | ringqExtRegistered | Phones and apps registered now |
| 1.4.0 | ringqExtTotal | Extensions that are switched on |
| 1.5.0 | ringqTrunksUp | SIP trunks that are up |
| 1.6.0 | ringqTrunksTotal | SIP trunks set up on the server |
| 1.7.0 | ringqQueueWaitingTotal | Callers waiting in all call queues |
| 1.8.0 | ringqRecDiskFreeMB | Free space on the recording disk (MB) |
| 1.15.0 | ringqRecDiskUsedPct | Used space on the recording disk (%) |
| 1.9.0 | ringqCallServicesUp | RingQ Call Services running (1 yes, 2 no) |
| 1.10.0 | ringqLicenceLimit | Calls at the same time the licence allows (absent when there is no limit) |
| 1.11.0 | ringqSafeCalls | Safe calls at the same time, from the last Capacity Test (absent until one is run) |
| 1.12.0 | ringqDataAge | Age of these numbers in seconds |
| 1.13.0 | ringqVersion | RingQ version |
| 1.14.0 | ringqBusy | Server very busy, last good numbers held (1 yes, 2 no) |
| 2.1.2.n | ringqTrunkName | Trunk table: trunk name, one row per trunk |
| 2.1.3.n | ringqTrunkState | Trunk table: 1 up, 2 down, 3 not registered |
| 3.1.2.n | ringqQueueName | Queue table: queue name or number |
| 3.1.3.n | ringqQueueWaiting | Queue table: callers waiting in that queue now |
Your tool can also read the standard values every SNMP tool knows: system name and uptime, network interfaces and traffic, CPU load, memory and disk use.
Suggested alerts
- ringqCallServicesUp is 2: RingQ Call Services is not running.
- ringqTrunksUp is lower than ringqTrunksTotal, or a row in the trunk table is 2 or 3: a carrier trunk is down.
- ringqRecDiskUsedPct above 85: recordings will soon fill the disk.
- ringqActiveCalls close to ringqSafeCalls or ringqLicenceLimit: the server is near its safe capacity.
- ringqQueueWaitingTotal above your normal level for more than a few minutes: callers are waiting too long.
- ringqDataAge above 300: the live numbers are stale and are left out until they refresh.
Advanced settings
Open Advanced to see or change the security details. Most customers leave them as they are.
| Setting | Default | Notes |
|---|---|---|
| Security level | authPriv | Fixed. RingQ only allows signed and encrypted polls. |
| Sign-in method | SHA-256 | Choose SHA for older tools. Changing it needs the password and encryption key again. |
| Encryption | AES-128 | Fixed. |
| Location | Empty | Optional text your tool shows as the device location, for example Data centre rack 4. |
| Contact | Empty | Optional text your tool shows as the device contact, for example IT help desk. |
RingQ Support monitoring
Separately from SNMP, the RingQ Support monitoring switch lets the RingQ Support team watch the health of your server so they can spot problems early and help faster. It is on by default and you can switch it off at any time on the same page.
- Only numbers are sent, such as calls up now, CPU, memory and disk use. No call content, recordings, names or phone numbers.
- Numbers are sent once a minute over the secure outbound RingQ Console connection. No port is opened on your server.
- It works on every server type, including servers where SNMP is not offered.
Shared (multi-tenant) servers
On shared servers several companies use the same machine, so SNMP is not shown. RingQ Support monitoring still watches the server for you. If you need your own monitoring of a shared system, contact RingQ Support.
Troubleshooting
| What you see | What to check |
|---|---|
| The tool gets no answer at all | Is Monitoring switched on? Is the tool's address in Who can poll? Is UDP 161 allowed in any firewall or cloud security group in front of the server? |
| Recent polls shows Refused | The poll came from an address that is not in Who can poll. Add the address shown in Recent polls, or the range it belongs to. |
| Recent polls shows Answered but the tool shows an error | Check the username, password, encryption key, SHA-256 or SHA, and AES in your tool. Remember the password and key are case sensitive. |
| Standard values work but RingQ values are empty | Import the RINGQ-MIB file, or walk the base OID directly. If ringqDataAge is above 300, wait a minute and poll again. |
| ringqBusy is 1 | The server was very busy and the tool is seeing the last good numbers. Check CPU use and the number of calls. |
| Save says the server is not ready | Press Update in Global Settings, then save again. |
Quick reference
| # | Action | Where |
|---|---|---|
| 1 | Open Monitoring | Global Settings > Troubleshooting > Monitoring |
| 2 | Add allowed addresses | Who can poll (up to 20) |
| 3 | Set username, password and encryption key | Sign-in details (never shown again) |
| 4 | Switch on and save | Status shows Waiting for a poll, then Working |
| 5 | Add the device to your tool | SNMPv3, authPriv, SHA-256, AES-128, UDP 161, import RINGQ-MIB |
| 6 | Test | Run the test command and check Recent polls |
Need help? Contact the RingQ team.