Compare commits
4
Commits
4623d9b7b0
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
 mrhid6
|
53629450e0 | ||
|
mrhid6
|
f230b66384 | ||
|
mrhid6
|
a1960b26ea | ||
|
mrhid6
|
d5e5377fae |
@@ -112,6 +112,17 @@ map $http_upgrade $connection_upgrade {
|
||||
'' close;
|
||||
}
|
||||
|
||||
# Heartbeat ping URLs carry a credential. Log them with the token replaced;
|
||||
# the header form (X-Vantage-Token) is never logged by this format.
|
||||
map $request_uri $vantage_log_uri {
|
||||
"~^/public/hb/(?!start(?:[/?]|$)|fail(?:[/?]|$))[^/?]+(?<hb_rest>.*)$" "/public/hb/***$hb_rest";
|
||||
default $request_uri;
|
||||
}
|
||||
|
||||
log_format vantage '$remote_addr - $remote_user [$time_local] '
|
||||
'"$request_method $vantage_log_uri $server_protocol" '
|
||||
'$status $body_bytes_sent "$http_referer" "$http_user_agent"';
|
||||
|
||||
upstream vantage_server {
|
||||
server server:8080;
|
||||
keepalive 16;
|
||||
@@ -127,6 +138,8 @@ server {
|
||||
listen [::]:80;
|
||||
server_name _;
|
||||
|
||||
access_log /var/log/nginx/access.log vantage;
|
||||
|
||||
client_max_body_size 10m;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
@@ -170,6 +183,12 @@ The `Upgrade`/`Connection` headers and `proxy_buffering off` are not optional:
|
||||
without them the browser console cannot open its WebSocket and live workflow
|
||||
logs arrive in bursts or not at all.
|
||||
|
||||
The `map` and `log_format` at the top are optional but recommended. A
|
||||
[heartbeat monitor](../vantage/heartbeat-monitors.md) ping URL contains a secret
|
||||
token, and this format writes it to the access log as `***`. If you use your
|
||||
own proxy instead, mask `/public/hb/<token>` the same way, or have jobs send
|
||||
the token in the `X-Vantage-Token` header.
|
||||
|
||||
### Terminating TLS in nginx
|
||||
|
||||
The shipped config speaks plain HTTP, which is right when another proxy or load
|
||||
|
||||
@@ -40,6 +40,9 @@ Four features are enabled per instance rather than bundled into a tier:
|
||||
No tier includes them by default; you enable them on the instances that need
|
||||
them.
|
||||
|
||||
[Patching](../vantage/patching.md) is available on every tier and is not a
|
||||
feature you enable: security patching is never paid for.
|
||||
|
||||
## Increases and reductions
|
||||
|
||||
An increase takes effect when payment confirms, and the entitlement is promoted
|
||||
|
||||
@@ -61,6 +61,7 @@ satisfies a `:read` requirement for it - you do not need to tick both.
|
||||
| `monitors` | Monitors, incidents, uptime and notification channels |
|
||||
| `vulns` | Vulnerability findings, packages and scan rules |
|
||||
| `workloads` | Containers and systemd units, including control actions and logs |
|
||||
| `patching` | Maintenance windows, patch policies and patch runs. `patching:write` creates and edits them and starts or cancels runs |
|
||||
| `settings` | Instance settings, members, single sign-on, licence, and token management itself |
|
||||
|
||||
A token created with only `servers:read` can list and inspect servers but
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
id: heartbeat-monitors
|
||||
title: Heartbeat monitors
|
||||
sidebar_label: Heartbeat monitors
|
||||
---
|
||||
|
||||
Backups and cron jobs fail silently. Nothing goes down, the job just doesn't
|
||||
run. A heartbeat monitor turns that silence into an incident: your job calls a
|
||||
URL each time it finishes, and Vantage alerts when the call stops arriving.
|
||||
|
||||
It is the opposite of every other [monitor](./monitors.md). Vantage does not
|
||||
check anything; it waits to be told.
|
||||
|
||||
## Creating one
|
||||
|
||||
1. Go to **Monitors** and choose **New monitor**.
|
||||
2. Pick **Heartbeat**.
|
||||
3. Set **Expected every (minutes)**: how often the job runs.
|
||||
4. Set **Grace (minutes)**: how late a ping may be before it counts as missed. The
|
||||
default is 5 minutes.
|
||||
5. Attach [notification channels](./notification-channels.md) and save.
|
||||
|
||||
The next page shows the **ping URL**, with ready-made `curl` commands.
|
||||
|
||||
:::warning Copy the URL now
|
||||
The URL contains a secret token, and it is shown only this once. Vantage
|
||||
stores a hash of the token, not the token itself, so it cannot show it to you
|
||||
again. If you lose it, use **Rotate token** on the monitor page to get a new
|
||||
one.
|
||||
:::
|
||||
|
||||
A new heartbeat stays **pending** until its first ping. It will not raise an
|
||||
incident before the job has ever run, so you can create the monitor before you
|
||||
deploy the job.
|
||||
|
||||
## Sending pings
|
||||
|
||||
Add a call to the end of your job:
|
||||
|
||||
```bash
|
||||
# success
|
||||
curl -fsS -m 10 --retry 3 https://vantage.example.com/public/hb/<token>
|
||||
```
|
||||
|
||||
Two more calls are optional:
|
||||
|
||||
| Call | Meaning |
|
||||
| ------------------------------ | ------------------------------------------------------------------ |
|
||||
| `/public/hb/<token>` | The job succeeded. The monitor goes up. |
|
||||
| `/public/hb/<token>/start` | The job started. Vantage measures the time until the next success. |
|
||||
| `/public/hb/<token>/fail` | The job failed. An incident opens straight away. |
|
||||
|
||||
Each accepts `GET` or `POST`, and answers `OK`.
|
||||
|
||||
A typical cron job using all three:
|
||||
|
||||
```bash
|
||||
URL=https://vantage.example.com/public/hb/<token>
|
||||
curl -fsS -m 10 "$URL/start"
|
||||
if backup-job 2>/tmp/backup.err; then
|
||||
curl -fsS -m 10 --retry 3 "$URL"
|
||||
else
|
||||
tail -c 1024 /tmp/backup.err | curl -fsS -m 10 --data-binary @- "$URL/fail"
|
||||
fi
|
||||
```
|
||||
|
||||
The body of a `/fail` request becomes the incident's cause and appears in the
|
||||
alert, so sending the end of the job's error output tells whoever gets paged
|
||||
what went wrong. Only the first 1 KB is kept.
|
||||
|
||||
### Keeping the token out of URLs
|
||||
|
||||
URLs end up in logs: your own proxy's, a load balancer's, an ingress
|
||||
controller's. If that matters, send the token in a header instead and call the
|
||||
path without it:
|
||||
|
||||
```bash
|
||||
curl -fsS -m 10 -X POST -H "X-Vantage-Token: <token>" https://vantage.example.com/public/hb
|
||||
curl -fsS -m 10 -X POST -H "X-Vantage-Token: <token>" https://vantage.example.com/public/hb/start
|
||||
curl -fsS -m 10 -X POST -H "X-Vantage-Token: <token>" https://vantage.example.com/public/hb/fail
|
||||
```
|
||||
|
||||
If a request carries a token in both places, the one in the URL is used.
|
||||
|
||||
Vantage's own request log, and the access log of the nginx bundled with the
|
||||
[self-hosted install](../getting-started/self-hosted-install.md#4-the-reverse-proxy),
|
||||
replace the token in a ping URL with `***`. Nginx's error log and any proxy you
|
||||
run in front of Vantage (on Kubernetes, the ingress controller) are not masked,
|
||||
so the header is the safer choice there.
|
||||
|
||||
## When an incident opens
|
||||
|
||||
| Situation | Incident cause |
|
||||
| ---------------------------------------------------------- | --------------------------------- |
|
||||
| No ping within the expected period plus grace | `no ping since <time>` |
|
||||
| A `/start` was not followed by a success within the grace | `started <time>, never finished` |
|
||||
| The job called `/fail` | `reported failure: <body>` |
|
||||
|
||||
Overdue heartbeats are checked every 30 seconds, so an alert can arrive up to
|
||||
half a minute after the deadline. Only a success ping closes the incident.
|
||||
|
||||
The grace time does two jobs: it is how late a regular ping may be, and how
|
||||
long a run may take after `/start`. Set it longer than your slowest normal run.
|
||||
|
||||
## Duration
|
||||
|
||||
When a job calls `/start` and then succeeds, the time between the two is
|
||||
recorded and shown as **Duration** on the monitor page, in place of the
|
||||
response time other monitors show. A backup that used to take 4 minutes and now
|
||||
takes 40 is worth knowing about before it starts overrunning.
|
||||
|
||||
## Limits and behaviour worth knowing
|
||||
|
||||
- **One request per second per token and call type.** A `/start` and the
|
||||
success ping in the same second are both accepted; two success pings in the
|
||||
same second are not, and the second gets `429`.
|
||||
- **Unknown token, disabled monitor:** both answer `404`, with no hint which.
|
||||
- **Disabling and re-enabling** a heartbeat resets it to pending, so a monitor
|
||||
switched off for a month does not page the moment it is switched back on.
|
||||
- **Rotating the token** stops the old URL working immediately, so update the
|
||||
job straight after.
|
||||
- A heartbeat is never run by an agent and has no interval or retries.
|
||||
|
||||
## API tokens and agents
|
||||
|
||||
Creating a heartbeat through the API or the [MCP agent](./mcp.md) returns the
|
||||
token once in the create response, as `heartbeat_token`. A monitor created
|
||||
through MCP is saved disabled, like any other.
|
||||
+2
-2
@@ -100,7 +100,7 @@ surface is a presentation layer over existing authority, not a new one.
|
||||
| `get_server` | Get one server's OS, online state and tags. | `mcp:read`, `servers:read` |
|
||||
| `list_monitors` | List monitors and their current state. | `mcp:read`, `monitors:read` |
|
||||
| `get_monitor_status` | Get one monitor's up/down/pending state, last check and last error. | `mcp:read`, `monitors:read` |
|
||||
| `list_incidents` | List monitor incidents (outages), most recent first. | `mcp:read`, `monitors:read` |
|
||||
| `list_incidents` | List monitor incidents (outages), most recent first. A tag-restricted token only sees metric alert incidents for servers inside its tags. | `mcp:read`, `monitors:read` |
|
||||
| `get_monitor_samples` | Get one monitor's recent raw check results. | `mcp:read`, `monitors:read` |
|
||||
| `list_workflows` | List workflows with step count, target count and whether each is scheduled. | `mcp:read`, `workflows:read` |
|
||||
| `get_workflow` | Get one workflow's ordered steps, targets and schedule. | `mcp:read`, `workflows:read` |
|
||||
@@ -119,7 +119,7 @@ surface is a presentation layer over existing authority, not a new one.
|
||||
| `assign_key` | Assign an SSH key to real servers. | `mcp:write`, `keys:write` |
|
||||
| `create_step` | Create a reusable workflow step. | `mcp:write`, `workflows:write` |
|
||||
| `create_workflow` | Create a workflow from existing step IDs. | `mcp:write`, `workflows:write` |
|
||||
| `create_monitor` | Create a monitor, saved disabled. | `mcp:write`, `monitors:write` |
|
||||
| `create_monitor` | Create a monitor, saved disabled. Supports every type, including `heartbeat` (the ping token is returned once) and `metric`. | `mcp:write`, `monitors:write` |
|
||||
|
||||
A known limitation worth calling out on `search_fleet`: its `version_below`
|
||||
argument is not implemented. Passing it gets you an error explaining that
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
id: metric-alerts
|
||||
title: Metric alerts
|
||||
sidebar_label: Metric alerts
|
||||
---
|
||||
|
||||
Agents already report disk, memory, load, reboot status and the state of every
|
||||
container and systemd unit. A metric alert turns those reports into incidents:
|
||||
"disk above 90% on any production server", "a systemd unit failed", "a reboot
|
||||
has been pending for more than 7 days".
|
||||
|
||||
One rule covers as many servers as its tags match. There is nothing to install:
|
||||
alerts use what agents already send, on any agent version.
|
||||
|
||||
## Creating a rule
|
||||
|
||||
1. Go to **Monitors** and choose **New monitor**.
|
||||
2. Pick **Server metric**.
|
||||
3. Under **Servers**, choose which servers by tag. Leave it empty to watch every server.
|
||||
4. Choose the **Metric** (the condition below) and its **Threshold**.
|
||||
5. Set **For (minutes)**: how long the condition must hold before it alerts.
|
||||
6. Attach [notification channels](./notification-channels.md) and save.
|
||||
|
||||
Tags are resolved each time the rule is checked, so a server tagged `env=prod`
|
||||
tomorrow is covered from then on, and a server whose tag is removed stops being
|
||||
watched.
|
||||
|
||||
## Conditions
|
||||
|
||||
| Metric | Alerts when | Threshold |
|
||||
| --------------------- | ---------------------------------------------------------- | --------- |
|
||||
| Disk used | Used space is at or above the threshold | percent |
|
||||
| Disk free below | Free space is at or below the threshold | GB |
|
||||
| Memory used | Used memory is at or above the threshold | percent |
|
||||
| Load per core | 1-minute load divided by CPU cores is at or above it | ratio |
|
||||
| Systemd unit failed | Any unit on the server is `failed` | none |
|
||||
| Container unhealthy | Any container's health check reports `unhealthy` | none |
|
||||
| Reboot pending for | The server has needed a reboot for at least this long | days |
|
||||
| Agent offline for | The agent has not been seen for at least this long | minutes |
|
||||
|
||||
The two disk metrics take an optional **Mount**, such as `/var`. Without one,
|
||||
every mount is checked and the fullest one is reported.
|
||||
|
||||
## How a rule decides
|
||||
|
||||
Rules are checked every 30 seconds, against each matching server separately.
|
||||
|
||||
- When a server first meets the condition, it becomes **pending**.
|
||||
- If the condition is still met after **For (minutes)**, the server goes
|
||||
**down**, an incident opens for that server, and the channels fire.
|
||||
- As soon as the condition clears, the server is **up** and its incident
|
||||
closes. A pending server that clears never alerts.
|
||||
|
||||
"For" is continuous: a server that drops below the threshold for one check
|
||||
starts the count again. Use it to ignore a nightly backup filling a disk for
|
||||
ten minutes, or a load spike during a deploy. Set it to 0 to alert on the first
|
||||
check.
|
||||
|
||||
### Per-server incidents
|
||||
|
||||
Each server has its own state and its own incident. If a rule matches 40
|
||||
servers and 3 are breaching, you get 3 incidents, and each alert names its
|
||||
server:
|
||||
|
||||
```text
|
||||
[Vantage] Disk full (metric) on web-01 is DOWN: /var 94.2% used
|
||||
```
|
||||
|
||||
The monitors list shows the rule as a whole, for example
|
||||
`3 of 40 servers breaching`. The rule's own page lists every matching server
|
||||
with its state, the current value and how long it has been breaching.
|
||||
|
||||
Webhook payloads carry a `server_name` field for metric alerts; see
|
||||
[notification channels](./notification-channels.md#webhook).
|
||||
|
||||
## Stale data
|
||||
|
||||
Agents send metrics every 30 seconds. If a server's last metrics are more than
|
||||
5 minutes old, the rule skips that server and keeps its previous state. A
|
||||
powered-off server does not suddenly clear, or trip, a disk alert.
|
||||
|
||||
To be told about the server itself going quiet, add an **Agent offline for**
|
||||
rule. It is the one metric that does not need fresh reports.
|
||||
|
||||
Some reports arrive less often:
|
||||
|
||||
- **Reboot pending** is refreshed with the agent's full inventory, every 15
|
||||
minutes and at agent start.
|
||||
- **Units and containers** are reported every 60 seconds.
|
||||
|
||||
## When servers leave a rule
|
||||
|
||||
If a server stops matching (its tag changed, or it was deleted) while it has an
|
||||
open incident, the incident is closed quietly, with no recovery message. Nothing
|
||||
recovered; the server simply stopped being watched.
|
||||
|
||||
## Tag-restricted API keys
|
||||
|
||||
An [API key restricted to tags](../reference/api-tokens.md#tag-restrictions) can
|
||||
only create a metric rule whose tags include all of its own. A key restricted
|
||||
to `env=staging` can create a rule for `env=staging role=web`, but not one for
|
||||
every server, and not one for `env=prod`.
|
||||
|
||||
The same key cannot rename, disable, change or delete an existing rule that
|
||||
reaches further than its tags, and it only sees incidents and per-server states
|
||||
for servers inside them.
|
||||
|
||||
## Status pages
|
||||
|
||||
A metric rule can be added to a [status page](./status-pages.md) like any other
|
||||
monitor. Its uptime reflects whether any matching server was down.
|
||||
@@ -4,8 +4,11 @@ title: Monitors
|
||||
sidebar_label: Monitors
|
||||
---
|
||||
|
||||
Monitors check that something is answering. Four types, two places they can run
|
||||
from, and a notification path when they stop being satisfied.
|
||||
Monitors check that something is answering. Four check types, two places they
|
||||
can run from, and a notification path when they stop being satisfied. Two more
|
||||
types watch for things that don't answer a check:
|
||||
[heartbeat monitors](./heartbeat-monitors.md) and
|
||||
[metric alerts](./metric-alerts.md).
|
||||
|
||||
## Types
|
||||
|
||||
@@ -19,6 +22,15 @@ from, and a notification path when they stop being satisfied.
|
||||
An `http` monitor with a keyword is usually the one you want for an application:
|
||||
a 200 that returns an error page still fails the keyword.
|
||||
|
||||
| Type | Watches | Guide |
|
||||
| ----------- | --------------------------------------------------------------------------- | ------------------------------------------- |
|
||||
| `heartbeat` | A job that calls a Vantage URL when it runs; alerts when the call stops | [Heartbeat monitors](./heartbeat-monitors.md) |
|
||||
| `metric` | Disk, memory, load, units, containers, reboots and agents on tagged servers | [Metric alerts](./metric-alerts.md) |
|
||||
|
||||
These two have no runner, interval or retries. The rest of this page is about
|
||||
the four check types; state, incidents, notifications and uptime work the same
|
||||
for all six.
|
||||
|
||||
## Where a check runs
|
||||
|
||||
Every monitor has a **runner**:
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
id: multi-factor-authentication
|
||||
title: Multi-factor authentication
|
||||
sidebar_label: Multi-factor authentication
|
||||
---
|
||||
|
||||
A second sign-in factor for password accounts, available on every plan, no
|
||||
licence required. Two kinds: an authenticator app (TOTP) and a passkey.
|
||||
|
||||
:::info Not for single sign-on accounts
|
||||
If you sign in through your organisation's identity provider, two-factor
|
||||
authentication and passkeys are set up there, not in Vantage. Your provider's
|
||||
own session policy applies instead.
|
||||
:::
|
||||
|
||||
## Setting up an authenticator app
|
||||
|
||||
1. Go to your account menu and choose **Security**.
|
||||
2. Under **Authenticator app**, choose **Set up**.
|
||||
3. Scan the QR code with an app such as Google Authenticator, 1Password or
|
||||
Authy, or enter the shown key manually if you cannot scan.
|
||||
4. Enter the 6-digit code the app displays to confirm it.
|
||||
|
||||
Once confirmed, you will be asked for a fresh code from that app every time
|
||||
you sign in with your password.
|
||||
|
||||
## Setting up a passkey
|
||||
|
||||
A passkey uses your device's built-in security (a fingerprint, face
|
||||
recognition, or a security key) instead of a code. It can be used two ways:
|
||||
as a second factor after your password, or on its own for **passwordless**
|
||||
sign-in.
|
||||
|
||||
1. Go to **Security** in your account menu.
|
||||
2. Under **Passkeys**, choose **Add a passkey**.
|
||||
3. Follow your browser or device's prompt.
|
||||
|
||||
Once added, the login page offers a **Sign in with passkey** button that
|
||||
needs no password at all, alongside the usual second-factor prompt if you
|
||||
sign in with a password instead.
|
||||
|
||||
You can add more than one passkey (for example, one per device) and rename or
|
||||
remove them individually from the Security page.
|
||||
|
||||
## Recovery codes
|
||||
|
||||
The first time you set up either factor, Vantage shows you ten **recovery
|
||||
codes**. Each one works once, in place of your authenticator app or passkey,
|
||||
if you lose access to both. Save them somewhere safe - a password manager or
|
||||
a printed copy - because they are shown only this one time.
|
||||
|
||||
If you run low, regenerate a fresh batch of ten from the Security page. This
|
||||
immediately invalidates every code from the previous batch.
|
||||
|
||||
:::warning Losing every factor and every recovery code
|
||||
If you lose your authenticator app, your passkeys and your recovery codes all
|
||||
at once, you cannot sign yourself back in. An owner or admin can reset your
|
||||
MFA from **Settings → People** (see below), after which you can sign in with
|
||||
your password and set up a new factor.
|
||||
:::
|
||||
|
||||
## Owners: requiring MFA for everyone
|
||||
|
||||
Owners can turn on **Require MFA for password sign-in** under **Settings →
|
||||
Access**. When this is on:
|
||||
|
||||
- Anyone signing in with a password who has not yet set up a factor is asked
|
||||
to enrol one immediately, before they can do anything else.
|
||||
- Anyone who already has a factor is unaffected beyond the normal prompt.
|
||||
- Members who sign in through single sign-on, or with a passkey used
|
||||
passwordlessly, already satisfy the requirement and are not interrupted.
|
||||
- People already signed in are not signed out. The requirement applies from
|
||||
their next sign-in.
|
||||
- Nobody who is required to have a factor can remove their last one - the
|
||||
**Remove** buttons on the Security page are disabled once removing them
|
||||
would leave the account with none.
|
||||
|
||||
## Resetting a locked-out member's MFA
|
||||
|
||||
If a member loses access to their authenticator app, their passkeys and their
|
||||
recovery codes, an owner or admin can clear their MFA entirely:
|
||||
|
||||
1. Go to **Settings → People**.
|
||||
2. Find the member and choose **Reset MFA**.
|
||||
3. Confirm your own identity when prompted (this is a sensitive action, so it
|
||||
asks you to re-authenticate first).
|
||||
|
||||
This removes their authenticator app, every passkey and every recovery code.
|
||||
They sign in with their password alone and are asked to set up a new factor
|
||||
on their next sign-in, or immediately if **Require MFA** is on.
|
||||
|
||||
An admin cannot reset an owner's MFA - only another owner can.
|
||||
|
||||
## Passkeys and moving your instance
|
||||
|
||||
A passkey is tied to the exact address you registered it on. If you later
|
||||
move a self-hosted instance to a new domain, or rename a cloud instance so
|
||||
its address changes, every passkey registered on the old address stops
|
||||
working - your browser and device will not offer them for a different host,
|
||||
by design of the WebAuthn standard itself.
|
||||
|
||||
Authenticator app codes and recovery codes are unaffected by a host change,
|
||||
since neither is bound to an address. If you rely on passkeys, plan to
|
||||
re-register them after moving or renaming an instance, and keep your recovery
|
||||
codes handy in the meantime.
|
||||
|
||||
## Re-confirming your identity for sensitive actions
|
||||
|
||||
A handful of actions ask you to confirm your identity again even while
|
||||
signed in, whether or not you have MFA enrolled: revealing a vault secret,
|
||||
downloading a private key, and connecting to the browser console. This
|
||||
confirmation (using your factor, or your password if you have none) is valid
|
||||
for ten minutes, so you are not asked again for a second sensitive action
|
||||
shortly after the first.
|
||||
|
||||
:::info API tokens are not prompted
|
||||
An API token performs these same actions with no re-confirmation step, since
|
||||
there is no person present to prompt. If this matters for your use case,
|
||||
issue narrowly scoped, short-lived tokens rather than broad ones.
|
||||
:::
|
||||
@@ -30,6 +30,9 @@ Posts JSON to a URL you choose.
|
||||
}
|
||||
```
|
||||
|
||||
Alerts from a [metric alert](./metric-alerts.md) add `"server_name"` with the
|
||||
server that breached. Other monitor types leave it out.
|
||||
|
||||
Any response of 300 or above counts as a delivery failure. The request times out
|
||||
after 10 seconds.
|
||||
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
id: patching
|
||||
title: Patching
|
||||
sidebar_label: Patching
|
||||
---
|
||||
|
||||
Patching installs OS updates on your servers inside a **maintenance window**
|
||||
you choose, and records what happened on every server. It is available on every
|
||||
tier: security patching is never a paid feature.
|
||||
|
||||
Three things work together:
|
||||
|
||||
| Thing | What it answers |
|
||||
| ----------------------- | ----------------------------------------------------------- |
|
||||
| A maintenance window | *When.* "Sundays 02:00 to 04:00, Europe/London" |
|
||||
| A patch policy | *What and where.* "Security updates on every `env:prod` server, reboot if needed" |
|
||||
| A patch run | *What happened.* One record per window, with a result per server |
|
||||
|
||||
Clicking **Apply updates** on a server or on the vulnerabilities page also
|
||||
creates a run, so every patch Vantage performs has a record.
|
||||
|
||||
## Maintenance windows
|
||||
|
||||
**Patching → Windows → New window.** A window has a name, a start time written
|
||||
as five-field cron, a timezone and a length from 15 minutes to 12 hours. The
|
||||
editor shows the next three windows, computed by the same code that opens
|
||||
them.
|
||||
|
||||
The timezone is stored by name, so a 02:00 window stays at 02:00 across
|
||||
daylight-saving changes. A window never starts while the previous one is still
|
||||
open, including on the night the clocks go back and 01:30 happens twice.
|
||||
|
||||
A window used by a policy cannot be deleted. Move the policy to another window
|
||||
first.
|
||||
|
||||
## Patch policies
|
||||
|
||||
**Patching → Policies → New policy.** Owners and admins can create policies.
|
||||
|
||||
| Setting | Meaning |
|
||||
| -------------- | ------- |
|
||||
| Window | The maintenance window the policy runs in |
|
||||
| Targets | Named servers, tags, or both, exactly as for [workflows](./workflows.md#targeting). Tags are read when the window opens |
|
||||
| What to install | **Security updates only** or **All pending updates** |
|
||||
| Reboots | **Never reboot**, or **Reboot if required** |
|
||||
| At most this many at once | How many servers patch at the same time. 0 means no limit |
|
||||
| Alert channels | Told when a run finishes with anything other than every server succeeding |
|
||||
|
||||
**Run now** opens a window of the policy's usual length starting immediately.
|
||||
It is the way to try a policy before trusting it with a Sunday.
|
||||
|
||||
### Security updates only
|
||||
|
||||
| Package manager | How security-only works |
|
||||
| --------------- | ----------------------- |
|
||||
| apt (Debian, Ubuntu) | Only your `-security` sources are used |
|
||||
| dnf, yum (RHEL, Rocky, Alma, Fedora) | `--security` |
|
||||
| zypper (SUSE) | Security patches only |
|
||||
| Windows | The Security Updates and Critical Updates classifications |
|
||||
| apk (Alpine), pacman (Arch) | **Not supported.** These publish no security metadata, so the server reports *unsupported* and nothing is installed |
|
||||
|
||||
Security-only never falls back to installing everything.
|
||||
|
||||
### Reboots
|
||||
|
||||
With **Reboot if required**, a server reboots only when its OS reports that a
|
||||
reboot is owed, and only if at least 5 minutes of the window remain. The agent
|
||||
reports first, then reboots after one minute.
|
||||
|
||||
Vantage then waits for the server to come back. The reboot counts as done when
|
||||
the agent reports a boot time later than the reboot, with no reboot still
|
||||
owed. A server that does not come back within 45 minutes is marked failed.
|
||||
|
||||
With **Never reboot**, the server shows **reboot required** instead.
|
||||
|
||||
## What happens during a window
|
||||
|
||||
- Servers start patching as the window opens, up to the concurrency limit.
|
||||
- A server whose agent is offline is retried while the window is open.
|
||||
- No server starts patching in the last 15 minutes of a window. Servers still
|
||||
waiting then are marked when the window closes.
|
||||
- Servers already patching are allowed to finish, even past the window end
|
||||
(up to 2 hours from when each started). Interrupting a package manager is
|
||||
worse than letting it finish late.
|
||||
- A reboot only happens if at least 5 minutes of the window remain.
|
||||
- A policy whose previous run is still going skips the window, and says so on
|
||||
the policy.
|
||||
|
||||
## Patch runs
|
||||
|
||||
**Patching → Runs** lists every run. Open one to see each server's result, how
|
||||
many updates were installed, reboot times, and the last part of the package
|
||||
manager's output.
|
||||
|
||||
| Server status | Meaning |
|
||||
| ------------- | ------- |
|
||||
| queued | Waiting for a concurrency slot |
|
||||
| waiting for agent | The agent is offline; retried while the window is open |
|
||||
| patching | Installing now |
|
||||
| rebooting | Rebooted; waiting for it to come back |
|
||||
| succeeded | Patched, and rebooted and back if a reboot was owed and allowed |
|
||||
| failed | The package manager failed, the agent did not answer, or the reboot did not complete |
|
||||
| unsupported | Security-only on a server with no security metadata |
|
||||
| agent too old | The agent must be updated before it can take part |
|
||||
| missed, offline | Offline for the whole window |
|
||||
| window closed | Still waiting when the window ended |
|
||||
| cancelled | The run was cancelled before this server started |
|
||||
|
||||
A run is **succeeded** when every server succeeded, **failed** when none did,
|
||||
and **partial** otherwise. Anyone can cancel a running run: servers already
|
||||
patching finish, and nothing further starts.
|
||||
|
||||
Runs are kept for the same time as workflow logs (**Settings → Monitoring**).
|
||||
|
||||
## Agent version
|
||||
|
||||
Patch policies need agent **1.4.0** or later. An older agent would ignore
|
||||
"security only" and install everything, so Vantage does not send it policy
|
||||
work: it shows **agent too old** until you update it
|
||||
(see [Agent updates](../operations/agent-updates.md)). **Apply updates** still
|
||||
works on an older agent, but the run cannot report a result.
|
||||
@@ -93,16 +93,16 @@ Agents check for pending package updates hourly and report the count - the
|
||||
machine's own package manager on Linux, the Windows Update COM API on Windows.
|
||||
From the server page you can:
|
||||
|
||||
- **Apply updates** runs that check's install path and reports back. The agent
|
||||
never reboots the machine; if one is owed, a **reboot required** badge
|
||||
appears on the next inventory snapshot instead.
|
||||
- **Apply updates** installs every pending update now, without rebooting, and
|
||||
opens the [patch run](./patching.md#patch-runs) recording the result. If a
|
||||
reboot is owed, a **reboot required** badge appears on the next inventory
|
||||
snapshot.
|
||||
- **Update agent** upgrades the Vantage agent on that machine. See
|
||||
[Agent updates](../operations/agent-updates.md).
|
||||
|
||||
:::warning Applying updates is not scheduled or staged
|
||||
It runs immediately, on that machine. If you need ordering, health checks or a
|
||||
test machine first, build it as a [workflow](./workflows.md) instead.
|
||||
:::
|
||||
The panel also shows which [patch policy](./patching.md) covers the server and
|
||||
when its next window opens. To patch on a schedule, security-only, or with
|
||||
reboots, use a patch policy.
|
||||
|
||||
### Console
|
||||
|
||||
|
||||
@@ -78,6 +78,12 @@ sign-in. Vantage refuses any change that would leave nobody able to sign in,
|
||||
whether that is switching off passwords or disabling your last provider. Keep
|
||||
one route open until everyone who needs access can use the new one.
|
||||
|
||||
### Require MFA
|
||||
|
||||
Owners can require a second sign-in factor for everyone signing in with a
|
||||
password. See [Multi-factor authentication](multi-factor-authentication.md)
|
||||
for what this does, how members enrol, and how to reset a locked-out member.
|
||||
|
||||
## Monitoring
|
||||
|
||||
- **Offline threshold**, how long a server may go unheard from before it is
|
||||
|
||||
@@ -55,12 +55,12 @@ against three-week-old data is not the same as a low count.
|
||||
|
||||
## Fixing something
|
||||
|
||||
A finding with a known fixed version gets an **Apply updates** button, which
|
||||
runs the same OS update the server page offers. There is no separate patching
|
||||
mechanism.
|
||||
A finding with a known fixed version gets an **Apply updates** button. It
|
||||
installs every pending update on that server now and opens the
|
||||
[patch run](./patching.md#patch-runs) so you can see the result.
|
||||
|
||||
Vantage never patches automatically. Applying updates is always something you
|
||||
ask for.
|
||||
To keep servers patched without clicking, create a
|
||||
[patch policy](./patching.md) with **Security updates only**.
|
||||
|
||||
## Accepting a finding
|
||||
|
||||
|
||||
@@ -26,12 +26,16 @@ const sidebars: SidebarsConfig = {
|
||||
"vantage/ssh-keys",
|
||||
"vantage/workflows",
|
||||
"vantage/monitors",
|
||||
"vantage/heartbeat-monitors",
|
||||
"vantage/metric-alerts",
|
||||
"vantage/vulnerabilities",
|
||||
"vantage/patching",
|
||||
"vantage/workloads",
|
||||
"vantage/notification-channels",
|
||||
"vantage/status-pages",
|
||||
"vantage/secrets",
|
||||
"vantage/browser-console",
|
||||
"vantage/multi-factor-authentication",
|
||||
"vantage/mcp",
|
||||
"vantage/audit-log",
|
||||
"vantage/settings",
|
||||
|
||||
Reference in New Issue
Block a user