clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 33
colibri/docs/guide/sl/architecture/control-plane-bridge.md
Sam & Claude 968534d528
Some checks are pending
CI / agent-jail-pkgs (pull_request) Waiting to run
Details
CI / rust (pull_request) Waiting to run
Details
CI / markdown (pull_request) Waiting to run
Details
CI / port (pull_request) Waiting to run
Details
refactor: kill→stop across API surface, CLI, TUI, and docs 
Clean sweep — no kill on the Colibri wire protocol, CLI surface,
TUI keybinding, or documentation. Backward-compat aliases removed;
daemon and client deploy together so no transitional period needed.

  Wire: KillAgent→StopAgent, "kill-agent"→"stop-agent" (no alias)
  CLI:  colibri kill→stop, Command::KillAgent→StopAgent
  Lib:  client.kill_agent()→stop_agent()
  TUI:  kill_selected()→stop_selected(), "kill"→"stop" label
  Docs: spawn/kill→spawn/stop, kill-agent→stop-agent (40+ instances)

  Retained kill only where it belongs:
  - child.kill() / handle.kill() (OS SIGKILL)
  - Unix kill(1) in sigterm tests
  - OOM kill, process-group kill comments (kernel mechanism)
2026-06-26 14:40:10 +02:00

5 KiB
Raw Blame History

title description
Most krmilne ravnine Dostop do krmilne ravnine Colibri med gostitelji prek omrežja Tailscale.

Vsak gostitelj poganja colibri-daemon, ki posluša na lokalni vtičnici Unix (samo lokalno). Most krmilne ravnine to vtičnico izpostavi kot vrata TCP na vmesniku Tailscale, da lahko drugi gostitelji v omrežju upravljajo krmilno ravnino — ustvarjajo opravila, registrirajo agente, opazujejo terminale — ne da bi bila vtičnica kdaj dosegljiva z javnega interneta.

operater / soležni gostitelj             premoščeni gostitelj
  nc <tailnet-ip> 9190  ──tailscale0──▶  socat TCP-LISTEN:9190
                                              │ (bind = naslov tailnet tega gostitelja)
                                              ▼
                                         UNIX-CONNECT /run/colibri/colibri.sock
                                              │
                                              ▼
                                         colibri-daemon

Izvedbe

Most je tanka prednja stran socat, ki jo nadzoruje upravitelj storitev gostitelja. Obe strani sta v repozitoriju:

Gostitelj Storitev Pakiranje
FreeBSD rc.d colibri_bridge packaging/freebsd/colibri_bridge.in
Linux systemd colibri-bridge.service packaging/linux/ (enota + env + nft + README)

Obe v bistvu poganjata:

socat TCP-LISTEN:9190,bind=<tailnet-naslov-tega-gostitelja>,fork,reuseaddr \
      UNIX-CONNECT:/run/colibri/colibri.sock

Enota za Linux doda freebind, da lahko socat poveže naslov tailnet, še preden ga tailscaled do konca vzpostavi, in se tako izogne tekmi pri zagonu. bind=<tailnet-naslov> poslušalca obdrži stran od vseh drugih vmesnikov, tudi če se požarni zid pozneje spremeni — to je obramba v globino, ne glavna vrata.

Omrežna vrata

Vrata mostu so odprta samo na vmesniku Tailscale, v izvornem požarnem zidu gostitelja:

  • FreeBSD (pf): pass in quick on tailscale0 proto tcp to port 9190 keep state
  • Linux (ufw): ufw allow in on tailscale0 to any port 9190 proto tcp

Na gostitelju s privzeto zavrnitvijo (npr. ufw) je javna stran že zaprta, zato je potreben le dovoljujoč vnos, vezan na vmesnik. Nabor pravil packaging/linux/colibri-bridge.nft je namenjen gostiteljem Linux, ki ne poganjajo ufw (privzeto sprejemajoča vhodna veriga); pod ufw je odveč.

Varnostni model — meja tailnet je avtorizacija

Vtičnica krmilne ravnine nima lastne avtentikacije. Ko je enkrat premoščena, lahko vsak soležnik, ki gostitelja doseže prek omrežja Tailscale, izda celoten nabor ukazov (spawn-agent, stop-agent, intake-task, terminal-*, …). Zato je meja Tailscale nadzor dostopa:

  • vrata omejite na poimenovane soležnike s politiko ACL v Tailscale na :9190, namesto da bi se zanašali le na pravilo požarnega zidu
  • vsak premoščeni gostitelj obravnavajte kot tak, ki podeljuje pooblastila krmilne ravnine celotnemu omrežju tailnet, dokler ACL tega ne zoži

Opombe glede nastavitve

  • V gitu ni pravih naslovov tailnet. Predloge nastavitev prinašajo ograde TAILSCALE_IP_REQUIRED; operater ob namestitvi vpiše gostiteljev lastni naslov (tailscale ip -4). Privzetki rc.d na FreeBSD se prav tako ne zaženejo, dokler naslov ni nastavljen.
  • Skladnost poti vtičnice. Most se poveže na /run/colibri/colibri.sock (FreeBSD: /var/run/colibri/colibri.sock); ozadnji proces mora biti zagnan z ujemajočim COLIBRI_DAEMON_SOCKET. Privzeta pot ozadnjega procesa je pod $XDG_DATA_HOME, do katere zaprta enota systemd (ProtectHome=yes) nima dostopa — uporabnikova domača mapa ni vidna. Obe poti usmerite na /run.
  • Uporabnik mostu mora biti v skupini vtičnice ozadnjega procesa (vtičnica je 0770, lastnik + skupina).

Preverjanje

Z drugega gostitelja v omrežju tailnet:

printf '{"cmd":"status"}\n' | nc -w2 <gostiteljev-tailnet-ip> 9190

Zdrav most vrne stanje ozadnjega procesa v obliki JSON (vključno z gostiteljem ozadnjega procesa), kar od konca do konca potrdi dosegljivost prek omrežja.

Način Hive — mati in hčere

Ko dva gostitelja stopita v omrežje Clawdie, se povežeta prek mostov krmilne ravnine in matičnega strežnika. Takrat govorimo v dvojini:

OSA in domedog sta vzpostavila most. Midva sva registrirala vsak svojega agenta. Mati naju je prepoznala po profilu strojne opreme in oba sprejela v hive. Zdaj si deliva opravila — kar en sprejme, drugi prevzame, če prvi nima pravih zmožnosti.

V hive načinu matični strežnik (mother) samodejno sprejema registracije, razporeja opravila med gostitelje in vodi evidenco o tem, kateri gostitelj je kaj izvedel. Dva gostitelja sta najmanjša hive celica; z vsakim dodatnim gostiteljem se mreža širi, mati pa ostaja ena.