Building a Meshwork network

Configuring Meshwork comes down to making sure each node knows its own name and domain and has at least one reachable peer. From there the domain builds up the remaining links on its own. All actions are performed in the web admin panel; changing Meshwork settings requires the administrator role. The exact fields and their location are described in the Web interface section.

Requirements and reachability

  • Network reachability. A node must be able to establish a TCP connection to a peer’s administrative web server. The port is taken from the peer address (“host:port”) or from the public port that the peer announces about itself (Node identity) — it is always the port on which the peer’s web server is configured, and, when HTTPS is enabled on the peer, its TLS port. The values for a fresh installation are given in Initial settings; the required port of a peer must be open to the other nodes.

  • HTTPS for auto-discovery over the internet. If auto-discovered domain nodes communicate over public (internet) addresses, they need to establish a secure connection (HTTPS) between themselves in order to safely confirm each other’s authenticity over the open network. Therefore enable HTTPS at least on the nodes through which discovery takes place. Enabling HTTPS takes effect after a server restart. If nodes are reachable only over public addresses and none is running HTTPS, direct auto-discovered links are not authenticated: the node is still visible (through relay from a peer), but its direct link is flagged with a reason (see Network map and resource catalog).

  • Local network — HTTPS not required. If domain nodes communicate over private addresses of a single trusted network (10.x.x.x, 172.16–31.x.x, 192.168.x.x, as well as 127.x.x.x and 169.254.x.x), a secure connection for auto-discovery is not needed — nodes confirm authenticity over plain HTTP as well. A node is recognized as local by its IP address, so on a local network specify peers precisely by IP addresses rather than by domain names. HTTPS can still be enabled — it will be used if available.

  • An explicit link works over HTTP as well — the HTTPS requirement does not apply to it in any case.

  • Name and secret are mandatory. A node participates in the network only if it has a name and a signing secret set. Without a name or without a secret, a node does not participate in Meshwork.

  • Name restrictions. A node name is 2 to 16 characters, a domain name is no longer than 16 characters; Latin letters, digits and the characters _, -, . are allowed. Spaces and other characters are not permitted (for example, the domain “Alex Home” cannot be set — use Alex_Home).

Node identity

In the server settings you define how the node presents itself on the network:

  • Node name — a short unique name by which the others recognize the node. An empty name means the node does not participate in the network.

  • Note — an arbitrary label for the node (for example, “Moscow, rack 3”), shown in the admin panel for convenience and having no effect on the network operation.

  • Domain — nodes with the same domain automatically find each other, share a common resource catalog and replicate alerts. An empty value disables auto-discovery (the node can operate only via the explicit list of peers).

  • Public ports (HTTP and HTTPS) — the ports the node reports to peers for reverse reachability under address translation (NAT). If not set, the node reports its own web server ports.

  • Additional domains (super-node mode) — the node takes part in the auto-discovery of each listed domain on equal terms with the main one. Resources remain isolated per domain — the node does not mix them.

Peers and secrets

Here you define which peers the node maintains a direct link with and how the parties verify each other. Requests between nodes are signed with a shared secret, so without matching secrets no link is established. The length of each secret is 16 to 128 characters.

The peer list consists of entries of the form “address — name — secret”:

  • Address of a peer — the “host:port” of its admin panel. An entry may have no address: such a peer is never called by this node (it only dials in itself) and is identified by name and secret — this is used for a node behind NAT that can only initiate a connection.

  • Name of a peer must exactly match the name set on the peer itself.

  • Shared secret of the link with this peer must be the same at both ends.

In addition to the peer list, a node has its own signing secret: with it the node signs its outgoing requests. A peer verifies the signature with the secret it stores for that node, so the node’s own secret must match the secret recorded about it on each peer.

Note

A practical rule: for a simple site, set one shared secret and use it both as the own signing secret on each node and as the secret in each peer entry — then any pair of nodes authenticates the same way. For stricter separation, you can keep a separate secret per link.

Quick start

Option A. Two nodes directly (explicit link)

The simplest Meshwork is two servers connected manually.

  1. On each node, set a unique short name (for example, node1 and node2).

  2. On each node, add a peer entry: the address of its admin panel, its name and the shared secret.

  3. On each node, set the own signing secret. The simplest approach is to keep a single shared secret for both nodes.

  4. Open the network map in the admin panel. Within a few seconds both nodes will see each other in the “online” state.

A domain need not be set for this, but without a common domain you will get only mutual visibility of the nodes. The shared resource catalog and alert replication work only between nodes with the same domain — if you need them, set a common domain for the nodes (option B).

Option B. A domain with auto-discovery

When there are more than two nodes, it is more convenient to give them a common domain rather than list each link manually.

  1. On each node, set a unique name and the common site domain.

  2. If domain nodes communicate over the internet (via public addresses), enable HTTPS on at least one or two domain nodes and restart them (see Requirements and reachability). On a local network this step can be skipped.

  3. Link the nodes via an “entry point”: on each node, specify at least one already working peer (address, name, shared secret), as in option A. The node will find the rest of the domain nodes on its own.

  4. Open the network map. Within a few seconds all domain nodes will appear on it: the explicitly specified ones as permanent, the automatically found ones as auto-discovered.

Nodes behind NAT

A node on a private network that cannot be reached directly from outside can fully take part in the network as an initiator. It establishes a connection to a reachable peer itself, and over this single connection data flows in both directions — the node both reports about itself and receives information about others. For such a node it is enough to specify at least one reachable peer.

Information about a NAT node spreads across the domain automatically: a peer that is online with it relays its state to the others. On distant peers such a node will be shown as received through relay, but in the “online” state.

To make a node behind NAT reachable for inbound connections as well (for example, to serve as a domain entry point), configure publishing of the public port (see Node identity) and forward this port on the router/firewall to the node’s administrative web server. On the peers’ side, such a node is kept as an entry “name + secret without address”: the peer will not vainly try to dial the private address but will identify the node by name and secret when it connects on its own.

Common problems

  • Nodes do not see each other. Check: both have a node name set; each has a signing secret and it matches the one recorded about it on the peer; the peer’s address is correct and its admin port is open to the other node.

  • A peer is in the “offline” state. The node has exceeded the waiting window: check the network and the operability of its web server. For a node behind NAT, make sure it initiates the connection to a reachable peer itself, or that port publishing and forwarding are configured.

  • An auto-discovered peer is flagged with a reason, the direct link does not work. The domain cannot confirm the authenticity of the nodes. If they communicate over the internet, enable HTTPS on at least one domain node and restart it; on a local network, check that peers are specified by IP addresses rather than domain names. Over an explicit link (permanent nodes) the link works without HTTPS too.

  • False NAT indication. If nodes are specified by domain names rather than by IP, the NAT indication may not be determined from the address — this does not interfere with operation. For reliable NAT diagnostics, use IP addresses.

  • Changing the domain “reset” the map. Changing the domain or the set of additional domains rebuilds membership: auto-discovered links and the shared catalog are temporarily reset and rebuilt. This is normal.