How to monitor particular kit with Oversight: which sensor to use, where on the device to set up access, which user function and extraction rows read the response, and how to write the rules that turn it into an alarm. Search for a vendor, a product or an error message, or ask a question in your own words.
Email in: job reports that can only be emailed
Some jobs can only report by email: a NAS, an old backup product, a control panel, an appliance with an SMTP setting and nothing else. Email in takes those reports and puts each one on a push channel on the Logs page, where it is read and judged worked or not worked exactly as a log sent over HTTPS is. See Pushed logs for how a log is judged and what happens when one did not work.
Oversight does not sign in to a mailbox to collect them. There is no IMAP, no service account, no password of yours held anywhere and no exception to MFA. The mail is delivered to Oversight itself, at one address for every account, shown on Setup > Ingestion.
Where a job can post, posting is still the better choice: it is immediate, and nothing between the job and Oversight can hold it up. Email is for the jobs that have no other way.
How a message finds its channel
Every message is checked in this order, and one that fails any step is deleted there, unread:
- SPF. The server the message came from must be allowed to send for its sender's domain, by that domain's SPF record. A message that fails SPF, or whose domain has no SPF record, is deleted.
- Your domain. The address it was sent from must be on one of your account's mail domains, or a subdomain of one:
example.co.ukcoversnas.example.co.uktoo. - Your routes. Your account's routes are tried in order, and the first that matches decides the channel. A message no route takes is deleted.
Only then is the message opened and its text stored. Nothing is ever sent back: no bounce, no reply and no receipt, whatever happens to a message.
Mail is collected every five minutes, and a stored message is then judged within a minute or two, so a report is usually judged within about seven minutes of being sent.
Mail domains
The domains your systems send from are set by GEN, and shown on Setup > Ingestion; raise a ticket to add or change one. A domain belongs to one account only, since the domain is the only thing that says whose mail a message is. When GEN adds a domain, its SPF record is shown alongside: a domain with no SPF record can never get anything through, and that is better found then than by waiting for mail that never arrives.
The address that counts is the one the mail was sent from, the envelope sender, which a received message shows in its Return-Path header. It is not the From: line, which anyone can write. Most systems use the same address for both, but not all.
Routes
Routes are on Setup > Ingestion, for anyone holding the Configuration permission. Each route has:
| Field | What it does |
|---|---|
| Sender | Optional. An exact address, backups@example.co.uk, or every address at a domain, *@example.co.uk. |
| Subject | Optional. A pattern for the whole subject, below. |
| Channel | The push channel on the Logs page. A new name makes the channel with the first message, as for a pushed log. |
| Order | Routes are tried lowest first, and the first to match takes the message. |
A route with neither a sender nor a subject takes everything from your domains that reaches it, so put it last. The list shows how many messages each route has stored and when it last stored one: a count that has stopped moving is how to see that a route has stopped matching, since a message no route takes leaves no trace.
Subject patterns
Written as a person would, not as a regular expression. Case is ignored, and the pattern must match the whole subject:
| Pattern | Matches |
|---|---|
*Hyper Backup* | Any subject with Hyper Backup in it |
Backup ? done | Backup 1 done, Backup 2 done |
~STATUS: | Any subject containing STATUS: |
[Virtualmin] Backup* | Exactly as written at the start, then anything |
* is any run of characters and ? any one, and a leading ~ means "contains". Everything else is taken literally, square brackets included, since subjects such as [Virtualmin] Backup complete are common. Quotes, semicolons and angle brackets cannot be typed into a pattern: use ? in their place.
Forward and reply prefixes are taken off the front of a subject before it is matched, however many there are: Re:, Fwd:, Fw:, AW:, WG: and TR:. So FW: Backup succeeded matches Backup succeeded*.
Trying a route
The Try panel on Setup > Ingestion takes a sender and a subject and says what would happen: stored on which channel by which route, or deleted, and why. SPF is not tried there, since it depends on the server a real message comes from.
Forwarding from a mailbox
A system that can email only one address, or that already reports to someone's mailbox, can be forwarded from that mailbox. That works when the forward keeps your domain as the sender:
- A forward by hand is sent from your own mailbox, so it carries your domain.
- An automatic forward from Microsoft 365, or from a cPanel or Exim forwarder, rewrites the sender so that SPF still passes, keeping your domain but changing the address in front of it with every message. A route on an exact sender then never matches: route on
*@and your domain, or on the subject alone.
A forward through a mail service that sends as its own domain, a personal Gmail account for instance, does not keep your domain and is deleted.
What is kept
- The text. The plain-text part where there is one; otherwise the HTML made into text, with table cells kept apart and links keeping their address in brackets. A message forwarded as an attachment is opened and its text used.
- The subject, which is the title the Logs page lists.
- Who sent it, with the
From:line, the date it gave and its message ID, all of which a filter can test withfield:fields.from,fields.header-from,fields.date, andfields.type, which is alwaysemail. - Attachments are not kept. Their names and sizes are listed at the end of the text, so a report sent only as a PDF reaches the model as a name and nothing more. Choose the job's plain-text or HTML report where it has one.
Text up to 8 MB is kept; anything longer is cut, and the log says so.
If nothing arrives
Because nothing is ever sent back, a message that does not arrive tells you nothing at your end. Check, in order:
- The domain. Is the address it is sent from on one of your mail domains? A NAS set up to send through a Gmail or Outlook.com account sends from that service's domain, not yours.
- SPF. Is the server that sends it allowed by your domain's SPF record? A device sending directly to the internet from an office line usually is not, unless that address is in the record; sending through your own mail server or relay usually fixes it.
- The route. Put the sender and subject into the Try panel. A subject pattern must match the whole subject, so
Backup completedoes not matchBackup complete on NAS01, andBackup complete*does. - The route's count. If it is going up, the mail is arriving: look on the channel on the Logs page.
Still stuck, raise a ticket with the time it was sent and the sender: GEN can see what happened to each message, though never its text.