Settings and system

Everything a household needs is in the web interface, for the administrators:

• Time zone (Settings): the hours of Internet, the reports and the nightly tasks follow the time of the box; in a container it is often UTC. The zone chosen in the interface (PUT /api/v1/time-zone {"zone": "Europe/Paris"}, "" for the system one) applies from the restart that follows, and the dashboard warns when the box and the browser are not on the same time. The installation assistant does too, at its step of the network: when the zone of the browser differs from the one of the box, it says so ("The box is on Etc/UTC, your browser on Europe/Paris…") and offers Use Europe/Paris (applied only on that click; Warda restarts). The same step shows the country of the box and where it comes from (see Country of the installation).

• Settings: learning (level, suggestions per week, your own domains), resolvers (Quad9 then Cloudflare, one of them, or your own), local network (zones sent to the box, address of http://warda) and journal (days kept, largest size). They are kept in the database and applied when Warda restarts; a setting given in /etc/default/warda (or a flag) keeps priority and is shown as fixed. The administration log records only the names of the settings changed (changed: custom_upstreams, journal_days), never their values: a value may carry an account or a token (the path of a DNS over HTTPS upstream).

• System: updates (with Docker, the daily check of new versions), on the Raspberry Pi image the updates of the system (see Updates of the system), backups, the terms of use and the anonymous statistics (see Terms of use and anonymous statistics), the maintenance actions below, restart of Warda, restart or power off of the box (Debian package: warda-system.path and warda-system.service, root, carry out the request of the service; the password of the account is asked again, the API token and the warda commands do not need it), and, in a card of its own, Diagnostic and support ("When something goes wrong: download the state of the box to look at it, or send it to the Warda team and give its code to the support"), a diagnostic to download and send: state, versions, settings, last warnings and errors, without any name asked by the devices, any name of the household (own domains and local zones are only counted) nor any secret: every address, in the settings as in the messages of the warnings and errors, keeps its scheme and host only (https://lists.example/…); see Diagnostic.

• Customer area (from 0.7.8 a page of its own, no longer a zone of System): link this box to an account, its plan; see Customer area.

Maintenance (System, POST /api/v1/maintenance/{action}, administrators; each action is confirmed, written to the administration log with what it removed, and one runs at a time):

• resolver — Restart the DNS resolver, without restarting Warda: empties the cache of the answers and starts the upstream servers again as new (their failures and waits forgotten, the connections kept open over DNS over TLS and HTTPS closed); what they did since the start and whether they validate DNSSEC are kept.
• network — Empty the network table: forgets the machines found by the network scan and their announcements (names, models, the equipment heard with LLDP and CDP) and the local names made for them; the devices of the household, their person or group and the names the family gave them stay. The next scan fills the table again.
• logs — Empty the logs: deletes the query journal and the live view (5 minutes); the statistics, the reports, the settings and the administration log stay.

Emptying asks the password of the account again (confirm_password), restarting the resolver does not; the API token does not need it. There is no warda command for them.

Mail server of the box#

From 0.8.5 (function mail-server of the catalogue; internal/mail, internal/admin/mail.go). The box sends e-mails (the summary of the week, nothing else) through an SMTP server an administrator gives: theirs, their provider's or their company's. Administration → Settings, card Mail server:

• SMTP server (a name or an address), Encryption: STARTTLS (port 587) (the default) or TLS from the start (port 465), Port (1 to 65535, the port of the encryption when empty), Account (optional), Password (only with an account), Sender (Warda <[email protected]> or an address).
• Never in clear: TLS 1.2 or later, the certificate of the server checked against the public authorities; a server that does not offer STARTTLS gets nothing ("the server does not offer STARTTLS: nothing is sent in clear"). Sign-in with PLAIN, or LOGIN for the servers without it, only over the encrypted connection. The connection waits 15 seconds at most, a whole sending a minute.
• The password is kept like the bind password of a directory: in the meta table (smtp, as the database is at rest), never given back by the API (password_set only), never written in the log, the diagnostic nor an error (an error of the server that would quote it shows ***); in the backups, which are encrypted, and given to the secondary of a pair with the configuration (which sends nothing while it is the secondary). Left empty, the password saved is kept, but only for the same server, port, encryption and account: otherwise whoever may change the settings could send it to a server of theirs ("type it again").
• Send a test message to an address, Send the test: 5 test messages in 10 minutes at most (409 beyond), with the settings typed.
• Remove the server: the box then sends no e-mail.

The mail server serves only the summary of the week: after the beta, without that function, the box refuses to set a server or to send a test (402), but the server kept (and its password) can still be seen and removed, and the card offers only to remove it. Administration log: mail.settings (smtp.example.org:587 starttls, account warda, from [email protected], or removed; never the password) and mail.test (through smtp.example.org:587: sent or failed). API (the system read or written): GET /api/v1/mail (host, port, security starttls or tls, username, from, password_set, configured), PUT /api/v1/mail (an empty host removes it), POST /api/v1/mail/test (the settings, to, lang; {"sent": true}).

Country of the installation#

The identifier of the installation (WRD-FR-1234-ABCD-EFGH, see Scheduled tasks) carries a country, also sent with the anonymous statistics. Up to 0.6.7 it came from the time zone of the box only, and a Raspberry Pi image on Europe/London put a box of Lille in the United Kingdom. Since 0.6.8 it is, in this order:

1. manual: the country an administrator chose in Administration → Settings, card Identifier of the installation (PUT /api/v1/instance {"country": "FR"}, audit instance.country): it is kept and the online service is no longer asked;
2. cloud: the country of the public address of the box, told by the online service of Warda (GET https://cloud.warda-dns.com/v1/whoami, unsigned, see cloud), which reads it from Cloudflare; audit instance.country.cloud when it changes;
3. timezone: the country of the time zone of the box (TZ, /etc/timezone or /etc/localtime), meanwhile, and when the online service cannot place the address (an answer without a country changes nothing).

The task Country of the installation (instance.country) asks the online service once the terms of use are accepted (nothing is asked before), at the start while the country came from the time zone, then once a week; an hour later after a failure; never while the country is manual. A change of country rewrites only the country of the identifier: its digits and characters stay. The card shows the source under the country ("The country of the public address of the box, told by the online service of Warda.", "Guessed from the time zone of the box (Etc/UTC) until…", "Chosen by an administrator: kept as is.") and, for a country chosen by hand, Find it automatically (PUT /api/v1/instance {"automatic": true}: the country of the time zone until the online service answers, asked at once; audit instance.country.automatic). GET /api/v1/instance gives id, country, source (cloud, timezone, manual), zone (the time zone of the box), zone_country (its country, empty for UTC) and countries. A box upgraded from 0.6.7 whose country an administrator had corrected (an instance.country entry in the administration log) keeps it as manual; the others are timezone until the online service answers. The source goes with the backups.

Terms of use and anonymous statistics#

The installation begins with the terms of use (version 2026-10-14, TermsVersion in internal/admin/terms.go; full text at https://warda-dns.com/<language>/terms/): a summary (free software under the AGPLv3, provided without warranty, what the box sends to the Internet, French law) and a box to tick. What the box sends to the Internet, all of it:

• the names asked by the devices, to the upstream DNS servers (Quad9 and Cloudflare by default), encrypted when they allow it, and the DNSSEC checks of these servers;
• the download of the lists (warda-lists, see Lists);
• the check of the new versions and the download of the signed updates (see Updates);
• the time, set by the system of the box;
• the monthly country database (DB-IP);
• the school holidays of the region chosen (OpenHolidays);
• the check of a new password against known leaks (Have I Been Pwned, k-anonymity: only the first 5 characters of the SHA-1 hash; off with WARDA_PASSWORD_BREACH_CHECK=false);
• from 0.8.0, when someone uses the Test a password of the Data breaches page: the first 5 characters of the SHA-1 the browser computed, to Pwned Passwords, from the box;
• from 0.8.0, with the plan, once the terms in force are accepted (2026-10-12, from 0.8.2 2026-10-13), for the addresses watched for known data breaches: 6 characters of the SHA-1 of each address, signed, to warda-cloud, which asks Have I Been Pwned; never the address;
• from 0.8.0, once the terms in force are accepted, the exposure on the Internet: a signed request to warda-cloud with a list of TCP ports (the external ports of the router mappings outside the fixed list), after which warda-cloud connects to the source address of that request only (the public address of the household) on those ports and on its fixed list, every week and on demand;
• from 0.8.0, only when an administrator turns on the protection outside the home: the hashes of the secrets of the enrolled devices and the answers to their queries, over a WebSocket to warda-cloud (the queries of the enrolled devices come, encrypted, through Cloudflare and warda-cloud; when the box cannot be reached warda-cloud answers them itself through Quad9 over DNS over TLS; it keeps only counts by day and the SHA-256 of the device secrets);
• when chosen, the online service warda-cloud (registration of the name of the encrypted DNS, the challenges of its certificate), the certificate authority (Let's Encrypt by default) and the API of a DNS provider when one is set (Cloudflare, OVHcloud);
• the question "which country is my public address in?", to warda-cloud (GET /v1/whoami, unsigned, nothing of the box in it), at the installation (once the terms are accepted) and once a week, unless an administrator chose the country by hand (see Country of the installation);
• unless the second opinion is turned off (Protection settings, card Look-alike names): a suspicious look-alike domain, alone, to warda-cloud to learn its age (see the second opinion);
• from 0.8.2, unless the reputation of the domains is turned off (Protection settings, on by default), once the terms in force are accepted: a domain the household does not know well, alone (the registrable domain, never the full name nor the device), signed, to warda-cloud, which asks the analysis service of Warda its opinion;
• from the terms of 2026-10-14, unless the second opinion is turned off (Protection settings, card Look-alike names), once those terms are accepted, with or without the collective base: each look-alike name found, as its registrable domain (in its DNS form), its kind (homograph, typosquat, combosquat, brandsub) and the name it imitates only when that name is a public site of the list built into the box (lookalike.Protected, lookalike.Public): a look-alike of one of the 500 names the household visits most goes without it; signed, POST /v1/domains/lookalikes, to warda-cloud, which passes it to the analysis service of Warda under the monthly pseudonym of the box (never its identity). Never the device, a person, a time or an address. Sent together a minute after the first one waits, then at most every 10 minutes, 50 names a request and 100 a day; a domain once a week at most (the domains sent are kept on the box a week, 2,000 at most, in the setting lookalike_reports of the meta table); 200 names waiting at most (package internal/lookalikereport; GET /api/v1/lookalike gives reports: sent since the start, waiting, last request, last error);
• the anonymous statistics below (a few times a day, counted once a day);
• only if an administrator turns it on (Protection → Collective base, off by default): registrable domain names only — the suggestions the administrators accept or reject, and the names the box doubts — to warda-cloud, which returns the opinion of the analysis service of Warda; never a device, a person, a time or an address, and the identity of the box is not passed to the analysis service (see Collective base);
• when an administrator sets it (Warda Business): the events chosen, to the collector of the company (see Export to a SIEM);
• when the box is in an organisation of sites (Warda Business): its state every 15 minutes, counts only, to warda-cloud, and, for the box of the manager, the list of the sites asked from it;
• only when an administrator asks for it (System → Send to the Warda team, or warda diagnostic -send): the diagnostic of the box, to warda-cloud (see Diagnostic).

The terms of 2026-10-12 (Warda 0.8.0) name the four items of 0.8.0 above, in the summary (terms.net.breaches, terms.net.relay, terms.net.exposure) and in the full text of the website (termsVersion in scripts/build.mjs of warda-website, the same date): a box updated to 0.8.0 shows the banner to its administrators until one of them accepts them. Two things wait for that version (TermsCurrent, as the collective base): the check of the exposure from outside (the router and the network are checked meanwhile, and the page says so) and the checks of the addresses watched for known breaches, the weekly ones and those asked by a person (409; the page says why, and the addresses added wait; accepting the terms starts them at once). The test of a password does not wait: it is a tool used on demand, not a setting, and only 5 characters of the hash leave the box. The protection outside the home does not wait either: it is off until an administrator turns it on, on a page that says what goes through Cloudflare and warda-cloud, and that explicit switch is the consent; the terms list it for the record.

The terms of 2026-10-13 (Warda 0.8.2) add the questions of the reputation of the domains (summary terms.net.reputation, and the full text of the website, the same date): a box updated to 0.8.2 shows the banner to its administrators until one of them accepts them. Everything that needs the version in force (TermsCurrent) waits until then: the collective base, the check of the exposure from outside, the checks of the known breaches, and the questions of the reputation of the domains (the card says "The questions wait for an administrator to accept the terms of use in force…"; read again at once on acceptance). The protection outside the home and the test of a password still do not wait, for the reasons above; the signing in with the directory sends nothing of the household to Warda's services (only to the directory, Microsoft or Google the company chose).

The terms of 2026-10-14 add the look-alike names reported to the analysis service of Warda even without the collective base (summary terms.net.lookalikes, the banner says what is new with terms.bannerNew, the help of the second opinion says it too, and the full text and the privacy policy of the website, the same date): a box updated shows the banner to its administrators until one of them accepts them. Nothing is queued nor sent before that acceptance, nor while the second opinion is off (what waits is dropped if either changes); and, as before, what needs the version in force (TermsCurrent) waits too: the collective base, the check of the exposure from outside, the checks of the known breaches and the questions of the reputation of the domains.

POST /api/v1/setup refuses an installation without "accept_terms": true and "terms_version": "2026-10-14"; it takes "telemetry": false to turn the statistics off at once. The choice of the statistics is recorded first, then the acceptance; an acceptance that cannot be recorded answers 500 (the accounts are made: sign in and accept on the System page). The version accepted, its time and its account are kept (terms_version, terms_accepted_at, terms_accepted_by of the database, shown on the System page, GET /api/v1/terms) and go with the backups; a backup made before the terms keeps the acceptance of the box, and one without a choice of the statistics (telemetry, on or off) keeps the choice of the box. A box installed before the terms, or new terms, show a banner to the administrators until one of them accepts them on the System page (POST /api/v1/terms {"accept": true, "version": "2026-10-14"}). The terms of 2026-09-30 add the collective base to what the box may send (only when it is turned on), and their summary (TermsSummary, the same version: no new acceptance) the country of the public address (terms.net.country: "the country of the public address of the box, asked to the online service of Warda at the installation and once a week (nothing of the box is sent); an administrator can set it by hand instead"), which the full text of the website lists too: a box that accepted an older version shows the banner again to the administrators until one of them accepts these. The collective base needs the version in force of the terms accepted (TermsCurrent: the one that describes it); it stays off until an administrator turns it on, and a box where it is on stops exchanging while newer terms wait to be accepted.

The terms of 2026-10-03 (Warda 0.7.10) add the plan of the box to the anonymous statistics (below): the data sent changes, so they are to accept again. A box updated to 0.7.10 that accepted an older version shows the banner to its administrators on every page ("An administrator has to accept the terms of use of Warda (version of 2026-10-03)", with Read and accept, which leads to the System page) until one of them accepts them there; the members see nothing. Meanwhile the filtering, the rules, the household and the interface work as before: nothing is blocked nor locked by the wait. Two things wait for the acceptance: the plan, left out of the statistics, which go on without it (TelemetryPlan), and the collective base when it is on, as said above. The card of the terms on the System page says so: "Until then, the anonymous statistics are not sent or, when an earlier version of the terms was accepted, go on as before, without what the new version adds." — they are held only on a box where no version was ever accepted.

Once the terms are accepted, Warda sends, unless turned off (System, PUT /api/v1/telemetry {"enabled": false}, and at the installation), exactly this to WARDA_CLOUD_URL + /v1/telemetry (POST, User-Agent: Warda/<version>):

{"id": "5f0c…(32 hexadecimal digits, random, drawn anew each day)", "version": "1.2.0", "install": "deb", "country": "FR", "arch": "arm64", "plan": "free"}

id is random, drawn anew the first time of each UTC day and kept on the box until the day ends only (telemetry_day; forgotten when the statistics are turned off): the service counts an installation once within a UTC day with it, and nothing links two days, the accounts, the subscription nor the identifier of the installation; install is docker in a container (/.dockerenv, /run/.containerenv), pi on the Raspberry Pi image (/etc/systemd/system/warda-os-updates.service), deb with the Debian package, else archive; country is the country chosen in Warda (the identifier of the installation), empty when unknown; arch is amd64, arm64, arm or other; plan (from 0.7.10) is free, subscription or business: the plan of the statement the customer area signed for this box, while it is valid (see Customer area), and free without one (a box in no account, a statement expired or refused, changed by hand or signed by another key). Nothing on the box sets it: no setting, flag, environment variable, command nor call of the API gives another (PUT /api/v1/telemetry takes enabled alone, a body that carries plan is refused, 400), and a statement added by hand to a backup is not restored. Only the kind of plan is told, never whose it is. The field is left out while the terms accepted are older than 2026-10-03, which did not list it; before any acceptance nothing is sent, and the installation shows what will be. It counts the installations, their versions, countries and plans. Since 0.7.0 the statistics go out 1 to 5 minutes after each start of Warda (an update included), then once in each half of the UTC day (00:00–12:00 and 12:00–24:00), at a random time of that half, so that the installations never send together. A box is still counted once a day: every send of a UTC day carries the identifier of that day, and the service replaces what it counted for that identifier (so an installation updated in a day counts once, with its last version). The statistics also go out 1 to 5 minutes after an administrator accepts the terms (at the installation or from the banner) or turns them back on. A send waits 15 seconds at most; a failure is logged as a warning (with the time of the next try) and tried again 15 to 30 minutes later, up to 3 times in the half-day, then at the next half-day; a success is logged at the info level. Showing what is sent while the statistics are off draws no identifier of the day.

GET /api/v1/telemetry shows what is sent (payload, with its plan from 0.7.10; under it the System page says "Plan sent: …. It comes only from what the customer area signs for this box (Free without it); nothing on the box can change it."), and the state of the sends: last_send (the last one tried, or the last one sent since the start), last_error (its error, empty when it went through) and next_send (the time planned). The System page shows them ("Last send: …, failed (…); tried again within 30 minutes", "Next send: …"), and Administration → Scheduled tasks lists the task Anonymous statistics (telemetry). The history, the names asked, the devices and anything of the network are never sent.

The units watch /var/lib/warda: with another data directory, restarting or powering off the box from the interface and the "Check now" of updates wait for the timer or do not work. A restored backup brings its settings back, including the local zones and the address of http://warda: check them after moving to another network.

Diagnostic#

When something goes wrong, the diagnostic gives the support what it needs to understand, without any name asked by the devices, any name of the household (own domains and local zones are only counted, the name of the encrypted DNS is left out) nor any secret: the version, the platform, the kind of installation (deb, pi, docker, archive), the uptime, the state of the DNS, of the lists and of the journal, the machine (CPU, memory, disk, temperature), the settings (upstreams with their scheme and host only), the updates, the backups, the categories, the state of the services and of the probes, the encrypted DNS (its mode, dates, protocols and errors), the scheduled tasks, the plan, counts (devices, people, rules, the threats and look-alike names on and found, the export to a SIEM) and the last 200 warnings and errors kept in memory (without the attributes that may hold a name). Every address, in the settings as inside the messages of the errors, keeps its scheme and host only: the private path of an upstream (a DNS over HTTPS path may carry an account) or of a list never reaches the diagnostic.

• Download: System → card Diagnostic and support → Download a diagnostic (POST /api/v1/diagnostic, a JSON file), or warda diagnostic [-o FILE] on the box (-o -: the standard output), through the socket of the service.
• Send to the Warda team: the button of the same card (after a confirmation that says what is sent) or warda diagnostic -send: the same diagnostic, compressed, goes signed by the key of the box to warda-cloud (POST /v1/diagnostics, see cloud), which keeps it 30 days under a code WD-XXXX-XXXX, shown on the page with a link to https://support.warda-dns.com (support): give the code to the support. POST /api/v1/diagnostic/send gives {"code", "bytes"} (409 without the online service); audit diagnostic.sent.

Restarts: why Warda restarted, and what is kept#

From 0.7.10 (internal/admin/starts.go, internal/store/stats.go, internal/journal, internal/sysinfo/history.go).

What the pages read. The dashboard, its charts and the reports read the database (the journal, and the counts by minute, hour and day), never counters of the memory: a restart, an update or a power cut does not, by itself, start them again from zero. Three defects did, and are fixed:

• A change of the time zone of the box. The counts by day are kept under the midnight of their day. With another zone (chosen in the interface, or in the system), the days counted before were no longer found: the week and the month read zero. At its start Warda now moves each such day to the day of the new zone that holds its noon, its counts added to those already there (stats_day, stats_block_day, stats_country, dlp_events, security_scores; logged as statistics by day moved to the time zone of the box). A day of the zone is the one that holds its own noon: where the clocks go forward at midnight (the Azores, Chile, Cuba) that day starts at 23:00 of the day before, and its statistics are kept as they are.
• A clock ahead at the start. A Raspberry Pi has no clock of its own: it may start with a wrong date, and the retention then deleted the whole history a minute after the start, before the network corrected the date. The retention of the journal and of the statistics now follows the running time of Warda: the time it is applied at goes forward at most 24 times as fast as Warda runs (a day of history for an hour of running; logged as retention behind the clock: it catches up with the running time of Warda). The other side of it: a box that was off for weeks keeps its oldest entries a little longer than the days set: the retention catches up one day for each hour Warda runs, so what is too old is purged progressively, never at once.
• The learning and the history of the box. The last analysis of the learning and its watched names are kept in the database; the last hour of the load and of the network card of the Health of the box is written to machine-history.json in the data directory (0600) every 5 minutes and when Warda stops, and read again at the start.

What is still lost, and for how long:

Why Warda restarted. Every start of Warda is written to the administration log (service.start, by system), with its reason in the detail (reason=update version=0.7.10 previous=0.7.9, reason=interface by=alice), found from what the run before left in the database: its version, the start of the machine it ran on, whether it stopped properly, and what asked it to restart. The first start with this log has no reason.

The chart of the activity of the dashboard marks every start of the period from that log (up to 0.7.9: only the last one, read from the start of the service), each with its reason in its tooltip; GET /api/v1/activity/events gives it as reason of the events restart and boot.

The ways Warda restarts by itself, and what each leaves:

• an update (at night between 02:00 and 05:00, or asked from the System page), and the rollback to the previous version when the new one does not stay up (Updates): update;
• the first certificate of the encrypted DNS, to serve the protocols chosen: certificate;
• a setting that needs a restart, changed in the interface: the Settings page saved, the time zone, the DHCP server of Warda turned on or off or its settings, the protocols of the encrypted DNS, the DHCP servers moved with the role in a pair: interface;
• a backup restored (restore), and on the secondary of a pair the configuration of the primary applied (primary);
• systemd, with the Debian package and the image: a Warda that does not answer for 30 seconds is stopped and started again (WatchdogSec), and one that stops for any reason is started again 2 seconds later (Restart=always): crash;
• the box itself: restarted from the interface (boot), or after a power cut (power). On the Raspberry Pi image the updates of the system never restart the box by themselves.

Reading why, on the box (Debian package and Raspberry Pi image): the journal of systemd holds the starts and the stops of Warda and of the units that restart it, over the last 7 days here:

sudo journalctl -u warda.service -u warda-update.service -u warda-system.service -u warda-rollback.service --since "-7 days" -o short-iso --no-pager | grep -E "systemd\[1\]|starting warda|shutting down|restarting|start of Warda|fatal error"

starting warda and shutting down are the start and the proper stop of the service, … : restarting what asked a restart from the interface, start of Warda written to the administration log carries the reason, fatal error an error that stopped it, and the lines of systemd[1] the watchdog, the restarts and the rollback. With Docker: docker logs warda.