Skip to content

Hosting a Node

rettui can host four kinds of node: a NomadNet node (pages and files) and an LXMF propagation node (messages kept for people who are offline), with your identity, an RRC hub (chat rooms), with one of its own, and an rngit node (git repositories, read over Reticulum), with another of its own.

NomadNet node

rettui hosts a NomadNet node itself. Pages are Micron files in node/pages/ (and downloads in node/files/) in the data directory, or the folder set in node_dir.

  • Forks and mirrors: someone who may make repositories in a group (c) can have the node fork or mirror a repository, and sync brings one up to date. The source can be an rns:// repository on another rngit node or an https:// one (GitHub, say), fetched by rettui itself; http:// and ssh are refused, because the node runs no programs. An https:// source can't carry a login or point at an address on your own network, redirects aren't followed, and a fetch stops when it takes too long or comes to more than rngit repository limit. The node fetches with its own identity, so give c only to people you trust to have it read what it may read. Mirrors are followed again once a day; a fork only when someone syncs it. The maker becomes the repository's administrator. A node can't fork or mirror from itself. A sync keeps branches and tags the source has dropped, as rngit does; switch on rngit mirrors drop what sources drop (git_host_prune) to have it remove them.
  • Switching it on: press h in the Node tab, use Start hosting in the web UI, or set "Host a node" in the settings. The node uses your identity, so its address stays the same. Its name defaults to your display name, and it announces every node_announce_interval_mins (360 by default) or when you press a.
  • Editing: the Node tab lists what's on the node and has an editor with Micron colouring, undo and redo, and a live preview, in both the TUI and the web UI. Show the editor and the preview side by side, the editor alone, or the preview alone (Ctrl-P / p, or the buttons in the web UI). Saving writes the file, and visitors get the new version straight away. New, renamed and deleted pages are picked up without a restart. You can also edit the files with any editor, or copy pages into the folder: rettui looks for new ones every minute.
  • Formatting ribbon: above the page editor, in both UIs, buttons put Micron markup around the selection, on the selected lines, or at the cursor: bold, italic, underline and normal (removes formatting), text and background colour, left/centre/right alignment, three heading levels, divider, literal block, comment, and inserting links, images, text fields, checkboxes and radio buttons, and uploading. Each has an Alt shortcut, the letter underlined on its button: Alt+B I U N, F G (colours), L C R, 1 2 3, V (divider) T (literal) O (comment), K (link) M (image) D (field) H (checkbox) A (radio) P (upload). Bold, italic and underline toggle, as do headings and comments. The web UI also takes Ctrl+B, I, U and K, and picks colours from a palette.
  • Pictures and files: Upload (Alt+P) adds a file to the node and puts it in the page where the cursor is (the selection, if any, becomes its label). The TUI asks for the file's path on this computer; the web UI picks files from the device, several at once, and files dropped on the page's text are added the same way. A picture (WebP, PNG, JPEG, BMP, GIF, TIFF) goes to pages/images/ and is shown in the page (`(name`:/media/images/name.jpg)). To suit the mesh it's made at most 1024 pixels across and written again as a JPEG (a PNG where it's see-through), which leaves out its metadata, such as where a photo was taken; a GIF (which may move), or one that wouldn't get smaller, stays as it is. A picture can be up to 512 KB. Anything else goes to files/, linked for visitors to download (`[name`:/file/name]), up to 32 MB. Names are made safe (spaces become -), and something already there is never replaced: the new one gets -2, -3... on its name. To add a picture or file without putting it in a page, press u in the TUI's list (it asks for the path), or + New › Upload a file in the web UI, whose + New asks whether to make a page or upload files. Pages link to it later by its address (Copy its address in its ⋯ menu).
  • Folders: the list shows pages/ (pages, and the pictures they show) and files/, each with its folders. In the TUI, n makes a page in the folder picked, r renames what's picked, m moves it to a folder of its root (a new one is made for it, and one left empty goes), and x deletes it. In the web UI, each has a ⋯ menu (open, show a picture, put it in the open page, copy its address, rename, move, delete), and on a computer anything can be dragged onto a folder of its root. Links to what's moved or renamed (:/page/, :/media/ and :/file/ addresses, and those naming your node's address; not links to another node's page of the same name) are changed in every page, except the one open with changes not saved (the TUI says so; the web UI changes them in the editor, for you to save). Scripts are never changed or moved this way, and the web UI can't rename or move them.
  • Who may see it: anyone, at first. To keep a page, picture or file to some people, press w in the TUI (or pick Who may see it… in its ⋯ menu in the web UI) and tick them: your contacts and those you've talked with show there once their key has been heard. rettui keeps the list beside it as name.allowed, a line for each identity, as NomadNet does, so lists made for NomadNet work too. Visitors who aren't on it, or who haven't identified themselves to your node, are refused. A list with no one on it lets no one see it (you still can, in the Browser). The node reads the list for each visit, so a change applies at once, and the list goes along when what it's for is renamed, moved or deleted. A list that's itself a program (executable) is left as it is: change it on the host. A list that isn't a file at all (a folder, a pipe) lets no one in. Copies an editor leaves beside a file are never served, as they have no list of their own: names ending in ~, .bak, .orig, .old, .tmp, .swp, .save or .rej, names wrapped in #, and any name with .allowed in it.
  • Statistics: the Node tab says how many pages, files and pictures the node has served, how many requests it had (and how many were for something not there), when the last one came, and since when it has counted, as NomadNet does. The counts are kept across restarts until you reset them, with R in the TUI or Reset in the web UI. While the node runs, Status shows them too. It also says (a Visitors line) how many different visitors who identified themselves have come since the node started (a visitor who doesn't identify can't be told apart, and this number starts again with the node).
  • Selecting text in the editors: Shift with the arrows, Home/End or PgUp/PgDn, Ctrl-A for everything, or drag with the mouse. Typing, pasting or deleting replaces the selection.
  • Starter page: a new node gets an index page with a short Micron guide.
  • Your own node in the Browser: a client can't reach a node it hosts over Reticulum, so rettui reads your own pages straight from the folder (never from the cache), and runs your script pages itself (see below).
  • Scripts: executable pages run as programs for visitors only when "Run page scripts" is on. The web UI can't change, rename or create scripts, turn "Run page scripts" on, change Script PATH or move the node folder, so the web login can't be used to run programs on the host. The TUI can do all of these.

Script pages

A script page is a program in pages/ that prints the page, as on NomadNet: any file with its execute bit set (chmod +x page.mu), usually starting with a line such as #!/usr/bin/env python3. Each visitor who opens it runs it, and gets what it prints. Scripts run only on Linux, macOS and other Unix systems, and only while "Run page scripts" is on: while it's off, a script is never sent, and a visitor who asks for one gets the same "not found" page as for a page that isn't there.

  • What a script gets: no shell and nothing to read on its input. Its environment holds only, as NomadNet gives it, link_id (the visitor's link), remote_identity (the identity hash of a visitor who identified), each field_… a form sent and each var_… a link sent, and PATH, which is /usr/bin:/bin unless Script PATH (Settings, Hosting; terminal only) says otherwise: a list of folders joined with colons, or host for the PATH rettui itself was started with, as NomadNet does. So #!/usr/bin/env python3 finds Python if it's in a folder on that path. Where it isn't (Homebrew, /usr/local, pyenv or a virtual environment), put its folder in Script PATH, or start the page with Python's full path, such as #!/opt/homebrew/bin/python3 or #!/srv/node/venv/bin/python. Use full paths: a script runs in the folder rettui was started in, not its page's folder, so #!../venv/bin/python or a relative Script PATH folder doesn't find it.
  • Limits: a script has 10 seconds to finish (Script time limit, up to 120) and may print up to 512 KB. Past either, or if it can't be run, the visitor gets a "Page failed" page saying it couldn't be made. A running script holds up the node's other requests until it ends, so a long limit makes everyone wait. What it writes to its error output never reaches visitors; a script that fails but printed something still sends that.
  • Trying one: open it on your own node in the Browser (b in the Node tab). It runs as it would for a visitor, with what a form sends, and as you if you identify to your node. When a visitor would get nothing, the page says why, shows what the script wrote to its error output, and, for a first line naming a program that scripts can't find, says where that program is on your computer. In the web UI, this runs scripts already on the node, as any visitor could; the web UI still can't write them or turn them on.
  • Docker: rettui's image has Python 3 (/usr/bin/python3), so #!/usr/bin/env python3 works there. For any other program, build an image on rettui's with it added.

Propagation node

A propagation node keeps messages for people who aren't online, until they collect them, as lxmd and other LXMF propagation nodes do. rettui's is built on rsLXMF's propagation node (its message store, stamp checks and peer protocol).

  • Switching it on: set "Host a propagation node" in the settings (Status tab, either UI). It announces itself (lxmf.propagation) a few seconds after it starts, then every announce_interval_mins, with its name (pn_name, or your display name), stamp cost and transfer limits. Its address comes from your identity, so it stays the same. Changing one of its settings restarts it; the messages it holds stay.
  • Status: the Status tab's Hosting messages line shows its address, how many messages it holds and their size, how many it has taken in and given out, those it refused, and the peers connected to it now. It's also listed in the Network tab, where you can pick it as your own propagation node.
  • What it takes: each message sent through it brings a propagation stamp of at least pn_stamp_cost (16 by default, LXMF's own; at least 13) less LXMF's flexibility of 3, and is at most pn_transfer_kb (256 KB by default). Clients send one message at a time; only peers send several. Messages without a valid stamp, too big, or over the storage limit are refused.
  • Storage: messages are kept encrypted for their recipients in propagation/ in the data directory, at most pn_storage_mb (500 MB by default). LXMF's 30-day expiry applies, and past the limit the oldest go first.
  • Limits on what it accepts: a copy of a message it already holds isn't checked again, a new message is checked once, outside the node's lock, a transfer with 16 bad stamps is refused, an /offer without a valid peering key is turned away before it is noted, and a peer can't ask for more than 10,240 KB in one sync.
  • Collecting: a client identifies itself on its Link and asks for its messages (/get); the node sends them, then deletes the ones it got.
  • Messages for you: when the node takes a message addressed to you, it delivers it straight to your conversations instead of keeping it. With your own node picked as your propagation node, rettui hands messages to it directly (a client can't open a Link to itself), and a sync has nothing to download.
  • Peers: other propagation nodes that peer with yours (proving the work of LXMF's peering key, cost 18) offer it the messages it doesn't have, and send them several at a time.
  • Passing messages on (peering): yours peers with other propagation nodes too, as lxmd does, so a message sent through it reaches its recipient whichever node they collect from. With Auto-peer (pn_autopeer, off until you turn it on) it peers with each propagation node it hears announcing within Auto-peer depth (pn_autopeer_depth, 4 hops), up to Most peers (pn_max_peers, 20). One that moves further away, or stops being a propagation node, is no longer peered with, and one asking for more work than LXMF allows (a peering cost over 26) isn't peered with at all. Static peers (pn_static_peers, addresses separated by commas) are always peered with, however far, once their announce has been heard. Every 24 seconds, one peer with messages it hasn't had is offered them, and sent those it wants; what each has had is kept with the node, so after a restart only new ones are offered. Turning Auto-peer off keeps messages here, and with static peers only. The Peered with line in Status (and the web UI's) says how many nodes it peers with and how many messages it has passed on.

Tested against Python LXMF 1.2: its clients send through and collect from rettui's node, and its propagation nodes peer with it.

Upgrading the propagation node

rettui 2.0 keeps the node's messages in the store rsLXMF 1.4 uses, which can't take over the folder an earlier version left in propagation/. If the node doesn't start, saying it can't open the message store, stop rettui and run:

rettui migrate-propagation

(in Docker, after docker compose down: docker compose run --rm rettui migrate-propagation). It moves the old messages to propagation.legacy-quarantine beside the store and starts a new one. The old messages are kept but not handed out again, since nothing can show where they came from, so people who had messages waiting on your node must send them again. Start rettui afterwards as usual. A node that never hosted a propagation node before needs nothing.

RRC hub

An RRC hub is what people chat on in RRC: rooms, their topics and modes, operators, bans. rettui runs rsRRCD's hub on its own Reticulum instance, so NomadNet, MeshChatX, Ratspeak, rettui and the other RRC clients can join it as they join rrcd.

  • Switching it on: press e in the Hub tab, use Start hosting in the web UI's Hub section, or set "Host an RRC hub" in the settings. It announces itself (rrc.hub) a few seconds after it starts, with its name, then every hub_announce_interval_mins (360 by default; 0 announces only when it starts), or when you press a. Its name is hub_name, or your display name; hub_greeting is sent to everyone who connects (\n starts a new line). Changing these applies to the hub as it runs: nobody is disconnected.
  • Its own identity: the hub has an identity of its own, made the first time it starts (rrc-hub-identity in the data directory), so its address stays the same and people who join learn the hub's address, not your LXMF one. You're an operator of it (as is the hub itself), wherever you are. If you use another identity (or the hub gets a new one), the old one is no longer an operator; operators added to its config.yaml by hand stay.
  • You on it: the hub is added to your hubs in Channels once it's up, and rettui joins it straight away (a client can't find a path to a destination it hosts, so yours connects with the hub's key). Stopping the hub leaves it.
  • Who makes rooms: only you, to start with: others join the rooms there are. With "Anyone makes rooms" (hub_open_rooms) on, as on most hubs, anyone may make a room by joining one that isn't there, and is its founder (an operator of it). A hub set up before this kept its setting.
  • Closed rooms and bans: someone who isn't in a room that is invite-only, has a key or is private can't post to it, list who's in it or read its topic, and only people in a room (or its operators) set its topic. A ban takes the person out on every connection they have.
  • Nicks and idle links: a nick is cleaned of control and invisible characters, and one someone else has (any case), or "hub", isn't given: the person is told, and keeps the one they had. Someone can only leave rooms they're in. Links are pinged every 60 seconds and closed if they don't answer within 30 more (ping_interval_s and ping_timeout_s in the hub's config.yaml; a value of 0 means these defaults).
  • Limits: one identity may hold at most 8 connections, a nick sent the older way is cleaned like any other, and a nick that looks like another (the same letters from another alphabet) isn't given. Joining, leaving and closing links don't rewrite rooms.yaml each time (at most every 5 seconds); at most 200 rooms may be registered, 8 per visitor. A link that doesn't say who it is within 30 seconds is closed, and no more than 64 may wait.
  • A damaged rooms file: if a crash leaves rooms.yaml cut off, it is put aside as rooms.yaml.damaged and rooms.yaml.bak (the rooms as they were when the hub last started) is used.
  • The Hub tab: who's connected (their nick, identity, rooms and when they came), the rooms (registered or not, modes, topic, who's in them, their operators) and the bans, of the whole hub and of each room. Pick someone to kick them from a room (K), ban them from one (b), make them an operator of one (o) or voiced in one (v), each again to undo, disconnect them (d), or ban them from the whole hub (B, a kline: they're disconnected, and every time they come back). Pick a room to set its topic (t) or modes (m: +m moderated, +i invite only, +t topic by operators, +n members only, +p private, +k key; - takes one off), or to register it (r). n makes a registered room, which stays, with its topic and modes, while nobody is in it. In Bans, x lifts the ban picked.
  • The web UI's Hub section: a room opens a page of its settings: its topic, a switch for each mode, its key, who's in it (with operator and voice to turn on or off, kick and ban), who's invited and who's banned, with renaming and deleting it at the bottom. A person opens theirs: the rooms they're in, with the same for each, and disconnecting or banning them from the hub. Bans each have a Lift button.
  • Renaming and deleting rooms: neither rsRRCD nor RRC has a command for them, so the hub does it itself. Renaming a room (R in the Hub tab) moves its topic, settings, key, operators and bans to the new name, and registers it. RRC can't move people from one room to another, so those in it are told the new name and taken out of the old one, to rejoin it there. Deleting a room (D, asked first) takes everyone out of it, telling them it's been closed, and it's gone with its settings and bans; where anyone makes rooms, anyone may make it again by joining it.
  • Hub commands: : in the Hub tab (or the web UI's console) runs a command as typed in a room, as the hub itself: /stats, /kline list, /who lobby, /reload... The hub's answers are listed beside it. The room commands (/topic, /mode, /op, /kick, /ban...) work in any room from here, though rsRRCD only lets a room's operators run them.
  • Its files: rsRRCD's own config.yaml and rooms.yaml (the registered rooms) in rrc-hub/ in the data directory, so its /reload and /kline work as they do in rsRRCD. rettui writes the settings above into config.yaml (and lists you and the hub as trusted_identities); the rest (limits such as max_rooms_per_session or rate_limit_msgs_per_minute, operators of your choosing, the hub's bans) is yours to change there, then /reload. Backups keep the folder, and the hub's identity with yours.

rngit repositories

rettui can serve git repositories to rngit clients, so people clone them over Reticulum with git clone rns://<address>/<group>/<name>.git (the stock rngit helper, git-remote-rns and rettui's Repos tab all work), and push to it. Cloning, fetching, pushing, creating repositories and deleting branches and tags work, and so do releases, work documents, changing who may do what, and forks, mirrors and sync.

  • Switching it on: set "Host rngit repositories" in Settings › Hosting (git_host_enabled). It announces itself (git.repositories) a few seconds after it starts, then every six hours. Status shows its address, as rns://<address>, and how many requests it has answered and refused.
  • Its repositories: a folder with a folder for each group and name.git repositories in each (git-host/ in the data directory, or the folder in "rngit repositories folder", git_host_dir, which only the terminal UI can set). Make them with git init --bare or git clone --bare. Backups keep the node's identity, not the repositories.
  • Its own identity: like the hub, the node has an identity of its own (git-host-identity in the data directory), made the first time it starts, so its address stays the same. Back it up with yours.
  • Who may read: nobody does until you say so. The easiest way is the table under Managing it below. Under it, each repository has a .allowed file beside it (demo.git.allowed), and a group a group.allowed in its folder, with rules like r:all (anyone), r:<32 hex identity> (one person) or adm:<32 hex>, one on each line or separated by commas. "rngit access" (git_host_access) in Settings › Hosting gives the same rules to every repository. A repository someone may not read looks like one that isn't there, so they're told "Not found". A line that isn't a rule is skipped, so a typo can only take access away. r reads, w pushes and deletes branches and tags, rw both, and c in a group's rules (a group.allowed, or "rngit access") lets someone make repositories there, if they identify themselves; the group's folder has to exist already. Whoever makes a repository is its admin (adm: in its .allowed). adm includes everything. Anyone who doesn't identify themselves is d7db22f63b453c23bb0688dde565b7c1, as in rngit.
  • Releases: a release of a repository is a tag with files and notes. Anyone who may read can list, read and download them (if they identify themselves, as rngit asks), and rel in the rules (rel:all, or rel:<32 hex>, or adm) lets someone publish, make latest and delete them. The tag has to be pushed first. They are kept beside the repository, in demo.git.releases/<tag>/, as stock rngit keeps them, with their notes, the files, each file's .rsg signature and the signed manifest.rsm the publisher made; the node keeps those and checks nothing, readers verify them. A tag is named with letters, digits and ._-+, a file by a plain name. A file may be 64 MB and a release 256 MB, and all of a repository's releases count towards its size limit. A release can only be added to while it is being published.
  • Limits: a clone's bundle or a push is held in memory and handled in one piece, up to rngit push limit (256 MB), and building or unpacking one stops after two minutes. A repository may come to rngit repository limit (1 GB) on disk, and a push that would go over is refused. A pushed pack is read before it is kept: it may hold 2 million objects, none over 128 MB once unpacked (a small delta that would grow into a huge file counts as the huge file), and 2 GB together. A fork, mirror or sync from an rns:// source is read the same way before it is kept; from an https:// source no object over 128 MB is unpacked. A group holds 1,000 repositories. Only branches and tags can be pushed; a branch moves forward unless the push is forced, and a tag stays where it is. A request over 1 MB is refused. Recent bundles are kept for ten minutes (64 MB in all), so the next clone of the same thing is quick; a branch that moves is a new bundle. rettui serves one request at a time, so a big clone makes the next client wait.
  • Managing it: H in the Repos tab, or ⌂ Hosted here at the top of the web UI's Repos list, lists what the node hosts, with each one's size and, for a fork or mirror, its source and when it last synced. From there you can mirror (m, Mirror) or fork (f, Fork) a repository from an rns:// or https:// URL, named after the source unless you name it (group/name; the group is made if it isn't there), make an empty one to push to (n, New), sync a fork or mirror now (s, Sync), rename one, even into another group (r, Rename: its releases, work documents and rules go with it), copy its clone URL (y) and delete it with its releases and work documents (X, Delete, asked first). These act on the folder as its owner, whatever the rules say, so the node's rules don't have to give you anything. The node has to be running. Each one says whether anyone can clone it, or only those its rules name.
  • Who may use each one: click a repository (or Enter on it in the terminal, Who may use it in the web UI) for a table of people and permissions: Read (clone), Push, Releases, Issues, Propose (work documents), Stats and Admin. Tick Anyone for everyone, No one to shut everyone out whatever the group says, or the people who may: your contacts and those you've talked with are listed once their keys are known, and you can add anyone by their LXMF address or identity hash (a in the terminal). A permission with nothing ticked is left to the group, then to rngit access. g (Its group…) does the same for the repository's group, with a Create column for who may make repositories in it. Saving writes the .allowed file, which the node reads for each request, so it applies at once; comments in it are dropped. A mirror or fork you make has no .allowed of its own, so until you tick something, the group's rules and rngit access decide who reads it.
  • Its pages: as stock rngit does with serve_nomadnet, the node also serves NomadNet pages to browse what it hosts, at a NomadNet address of the same identity, announced with the node's name. They list its groups and repositories (with each one's description, from its description file), and for each repository its clone command, its files, its README (Markdown formatted, with links to other files in it made into page links; one over 8 MB isn't shown), each file with its lines numbered and its syntax coloured, its history 50 commits a page, each commit with the files it changed, and its branches and tags. A file is shown 1,000 lines a page; one over 8 MB can only be downloaded, and one over 1 MB is shown without colour. Markdown and Micron files are shown formatted, with a link to their source. Every visitor sees only the repositories they may read, as for a clone, and anyone who doesn't identify sees what d7db22f63b453c23bb0688dde565b7c1 may. The pages use stock rngit's paths and page variables (/page/repo.mu with g and r, /page/blob.mu with ref and path...), so links made for one work on the other. b in the list of what's hosted (Pages in the web UI) opens them in the Browser: a repository's, or with nothing picked the list of them all. You see them as a visitor would, made here, since a client can't open a link to itself. rngit pages (git_host_pages, on) in Settings › Hosting turns them off. Colouring knows Rust, Python, C and C++, Go, JavaScript and TypeScript, Java, Kotlin, C#, Swift, Zig, shell, Lua, Ruby, SQL, TOML, INI, YAML, JSON, HTML, XML, CSS, Makefiles, Dockerfiles, diffs, Markdown and Micron, by a file's name, or for a script by its #! line.
  • Security: the web UI can switch it on and off, name it, make, mirror, fork, sync, rename and delete repositories, say who may use them and turn its pages on or off, but can't pick the folder. Nothing in a repository is run: hooks are never called. Names that aren't plain folder names (.., a leading dot, a path) are refused.

rngit serve DIR [RULES] of the rngit command serves a folder the same way without rettui.

Blocked contacts

Someone you've blocked (in Contacts) is turned away by everything you host: your node doesn't answer them, your hub closes their connection, your propagation node refuses their requests, and your git host refuses them. They can only be told apart once they identify themselves to the service, so a visitor who doesn't is treated as anyone. The git host reads the block list when it starts: switch it off and on to apply a change, and it knows only people rettui has heard announce.