Repository navigation
An answer about a server could describe the wrong machine, come back in another shape, or not come back at all, and answering n to trust --reset left a server with no host key, so the next connection trusted whatever answered; an answer now describes the machine it names or says why it cannot, comes in the shape it has for this machine, and --reset keeps the old key until the new one is accepted.
Four things to check before upgrading. On the container image, a local: true server is refused wherever its readings would have been the container's: the dashboard routes that read this machine answer 501, and --all and --server exit 1 for status, alerts, ports, processes, report, doctor and network scan, so a Homepage widget pointed at /api/report or a cron job running status --all over such a config gets an error where it got the container's numbers. A script that read a server's answer in its remote shape gets the local one: open_ports with a server and /api/ports?server=<name> answer {"ports": […]}, /api/processes?server=<name> answers the bare list, and watch add, watch remove and a watch check with nothing to check print JSON under --json. watch_add with a unit fails against a server on 1.7.0 or older instead of watching the wrong name, so upgrade the servers or leave unit out. And under --server, a command that printed its result and then failed, such as backup drill or doctor --strict, now prints that result on stdout before it exits 1, and the server's stderr goes to stderr instead of into stdout; over MCP, backup_drill and notify_test answer with the failed result instead of an error. The trust fix needs only the machine trust runs on upgraded, and a @cert-authority line that holds a server's old key is still neither removed nor reported.
⚠️ Behavior changes
- Inside a container, every dashboard route that reads this machine refuses as
GET /api/statusdoes (#400).GET /api/servers/<name>/statusfor a server markedlocal: trueanswered 200 with the container's own CPU, memory and disks as that server's, while/api/statusrefused the same reading./api/processes,/api/alerts,/api/ports,GET /api/report,POST /api/report/snapshotand/api/doctor, with noserveror with one markedlocal: true, did the same, andreportanddoctorput the server's name on them. Each now answers501with{"error":"homebutler is running in a container, which cannot see the machine it is on. …"}, the body/api/statusgives. A Homepage widget or script pointed at/api/reporton the container image gets that error instead of a report about the container; point it at?server=<name>for a server reached over SSH, which works as before. The docker routes, which reach whatever daemon the mounted socket leads to, are unchanged. Nothing changes outside a container - The dashboard opens on a server it can read, and the Report tab follows the server picker (#400). In the image, a config with only SSH servers left the picker empty, so the Dashboard tab showed the refusal in four cards, and the Report tab asked about the container and showed nothing but the refusal, Doctor and Save a snapshot included. The dashboard now opens on the local server when it can be read and otherwise on the first one that can; a
local: trueserver in the image is still listed, as(local, not visible from this container). The picker shows on the Report tab too, and the report, the doctor findings and Save a snapshot are for the server it names, so saving from the Report tab with an SSH server picked saves the snapshot on that server. A report or doctor reading that fails is shown in its own section and the rest of the tab stays.GET /api/serversgives each server avisiblefield,falseonly for alocal: trueserver inside a container - Inside a container,
--alland--serverrefuse alocal: trueserver forstatus,alerts,ports,processes,report,doctorandnetwork scan(#400).status --allprinted the container's readings on that server's line andstatus --server <name>printed them as its own. The--allline is now❌with the same sentence, and so the run exits 1 as any failed server does;--serverexits 1 with it. The SSH servers in the same run are still asked.docker list,docker statsandbackup listare unchanged, and so is a command run with neither flag /api/processes?server=<name>and/api/ports?server=<name>answer in the shape the same route gives for this machine (#402, #403)./api/processesfor an SSH server wasprocesses --json's{"processes": […], "total": n}where the local route is the list on its own, and/api/portsfor one wasports --json's bare list where the local route is{"ports": […]}. A script that read either the remote way gets the local shape now, and a remote answer in neither shape is a 502 rather than passed on.processes --jsonandports --jsonare unchanged, and so are both routes for this machine- The MCP tool
open_portsanswers{"ports": […]}when given aserver, as it does without one (#403). For a server it passed onports --json's bare list, in every release since the MCP server was added, while the answerdocs/compatibility.mdfreezes for the tool isports.Result. This is a fix toward that documented contract: a client that read the bare list for a server gets the object now, the same one it gets for this machine. The MCP toolprocesses, given a server running a homebutler older than 0.12.0, which printed the list without a total, refuses it with a request to upgrade instead of passing it on in another shape; the dashboard's/api/processes?server=<name>still reads that list watch add --jsonandwatch remove --jsonprint{"container", "kind", "added"}and{"container", "removed"}, andwatch check --jsonprints{"checked": 0}when nothing is watched (#403). Each printed a sentence even under--json. A script that matched on that sentence under--jsongets JSON now; without--jsonthe sentences are unchanged- The MCP tool
watch_addwith aunit, pointed at a server on 1.7.0 or older, fails instead of adding the target under the wrong name (#404). The unit is now sent aswatch add --unit, which those releases do not have, so the server refuses the flag before touching its watch list and the error names the server's version and the flag it lacks. Upgrade the server, or leaveunitout, which works as before against any release.backup_createwithexcludedoes the same against a server older than 0.40.0, where it archived the paths it was told to leave out watch addand the MCP toolwatch_addrefuse a name or unit that starts with-, andwatch_addwithout a server refuses the nameswatch addalready did (#404). Both are passed todocker,systemctl,journalctlandpm2as an argument, where a leading-is an option: a unit of--helpbecamesystemctl restart --help, which exits 0 and was counted as a restart.watch_addfor this machine stored anycontainerandunitit was given, spaces, slashes and;included, while the same call naming a server was refused there; it now refuses them withinvalid nameorinvalid unit, aswatch adddoes. Only adding is checked: a target already on a watch list keeps working, andwatch removestill takes it off- The MCP tools
backup_drillandnotify_testgiven aserveranswer with theDrillResultor the per-channel results when a drill fails or a channel does not send, as they do without one (#405). The server's command exits 1 in both cases, and that made the call an error whose message had the JSON pasted into it, so an agent was told the call failed instead of which step broke or which channel. An agent that took that error to mean the drill failed should readpassed, or eachsent, as it already does for this machine. A failing exit is an answer only for these two tools, and only when the document says the same failure; anything else, a connection that failed, a missing binary, output that is not JSON, stays an error with the server's stderr in it --serverpasses on what the command printed before it failed, and keeps the server's stderr on stderr (#405).backup drill <app> --server <name> --json,notify testanddoctor --strictprinted nothing on stdout when the result was a failure, and exited 1 with the result inside aremote command failed … homebutler deploymessage. They now print the result and exit 1 with the server's own sentence, such as[rpi5] vaultwarden did not come back from the backup, as running the command there does, with any warning it printed before that sentence on its own line above it; a server that printed its answer and no sentence exits 1 with[rpi5] exited with status N. What a server printed on stderr beside a successful answer, such as a deprecation warning, used to be printed into stdout ahead of the JSON; it now goes to stderr
🔐 Security
trust <server> --resetdeleted the server'sknown_hostsentry before it showed the new fingerprint, so answeringnleft no key at all (#401).--resetis what the host-key-changed error tells you to run, and answering no is how you say the new fingerprint is not the one you expected; the next key-authenticated connection then found nothing recorded and trusted whatever answered, which is exactly what the old key was there to stop. A host that could not be reached lost its entry the same way. The old entries are now replaced only after ay, in one write that swaps the file whole; answeringn, giving no answer, pressing Ctrl-C at the prompt, or failing to connect leavesknown_hostsbyte for byte as it was. The prompt under--resetnow says it will replace the keys, and the command reportshost key for <server> replaced in known_hosts. There is no non-interactive way to reset trust:trusthas no--yes, and neither MCP nor the dashboard exposes ittrust <server> --resetsaidreplacedwhile the old key was still trusted beside the new one (#401). Only entries written exactly ashostor[host]:portwere removed, so the hashed names OpenSSH records by default on Debian and Ubuntu (|1|…, fromHashKnownHosts yes) and[host]:22kept the old key, and a connection went on accepting either. Those are now removed too, matched the way a connection matches them. A wildcard line such as192.168.0.* ssh-ed25519 …that still accepts the old key is someone's own rule for many hosts, so it is left as it was: the new key is recorded, and the command names the line and exits 1 instead of reporting the key replaced.@revokedlines are never removed. A@cert-authorityline that holds the server's old host key is neither rewritten nor detected: it goes on accepting that key, and the command still reports it replaced. Aknown_hostswith a line that cannot be parsed is left as it was, and the error names the file and the line. Aknown_hoststhat is a symlink to a file that does not exist yet is written through to where it points, where it was replaced by a regular file; if the directory it points into is missing, or the chain is longer than 40 links, the command fails and leaves the link alone
🐛 Fixes
- the dashboard's Top Processes card showed only its header for an SSH server, and its Network Ports card showed nothing for this machine, not even "No open ports detected" (#402). Each card read one shape and its route answered the other for one kind of server, which the demo did not, so nothing caught it. The ports card has been blank for this machine since 0.11.2
- the MCP tools
watch_addandwatch_removefailed withinvalid JSON from remotefor every server, after the remote had already changed its watch list, andwatch_checkfailed the same way for a server watching nothing (#403). The remote's--jsonprinted a sentence. They now answer as they do locally, from a remote on this release or on an older one, whose sentences are read as the outcome they report - the MCP tools
watch_addandbackup_create, given aserver, droppedunitandexcludeand reported success (#404). A systemd unit or PM2 app added aswebwithunit: nginx.servicewas watched asweb, a unit that is not there, and a backup told to leave out/mnt/mediaarchived it. Both are now sent, andwatch addtakes the unit as--unit, which it did not have. Every other argument of the 26 tools that take a server already reached it, and a test now fails for an argument that does not, unless it is marked local-only with a reason. Anexcludepath with a comma in it arrives as one path - a server's stderr was read as part of its answer, so a warning printed beside the JSON broke it (#405). A server that still had
~/.homebutler/alerts.yamlmadenotify_testfail withinvalid JSON from remote, after the test message had gone out, and a drill whose record could not be saved did the same tobackup_drill. The MCP server, the dashboard,--alland the TUI now read only stdout as the answer, and stderr is still in the error when the command fails
📚 Documentation
docs/docker.mdlists the dashboard routes and the--alland--servercommands that refuse alocal: trueserver inside a container, and says the image's dashboard opens on a server it can read;docs/web-dashboard.mdsays the Report tab and Save a snapshot are for the server picked in the header (#400)- the README shows
watch add --kind systemd web --unit nginx.service, a target listed under one name and checked under another (#404)