3 There currently are three different types of configuration files in MeshLink:
5 - the main configuration file
6 - the host config files
7 - pending invitation files
9 All configuration files are in PackMessage format. The contents will be
12 There are three different ways envisioned to store configuration data:
16 - ephemeral, in-memory storage
18 To keep things as simple and flexible as possible, there are some restrictions:
20 - Configuration files are read from and written to memory in one go.
21 When a configuration files is changed, it is not modified in place,
22 but has to be written from scratch.
23 - When in-memory, functions from `packmsg.h` can be used to parse and generate the configuration data.
24 - Configuration files are read and written only via functions declared in `conf.h`.
25 This also includes creating and destroying the configuration directory.
27 ## Main configuration file
29 When stored on disk, it's in `meshlink.conf`. The contents are:
31 - uint32: configuration format version
32 - str: name of the local node
33 - bin: private Ed25519 key
34 - bin: private Ed25519 key for invitations
35 - uint16: port number of the local node
37 More information about the local node is stored in its host config file.
39 ## Host configuration files
41 When stored on disk, there is one file per node in the mesh, inside the directory `hosts/`.
42 The contents of a host configuration are:
44 - uint32: configuration format version
45 - str: name of the node
46 - str: name of the submesh this node is part of, or "." if it's in the core mesh
49 - bin: public Ed25519 key, or zero-length if no key is known
50 - str: canonical address (may be zero length if unset)
51 - arr[ext]: recent addresses
55 When stored on disk, there is one file per pending invitation, inside the directory `invitations/`.
56 The contents of an invitation file are:
58 - uint32: invitation format version
59 - str: name of the invitee
60 - str: name of the submesh this node will be part of, or "." if it's in the core mesh
61 - int32: device class of the invitee (may be unused)
62 - arr[bin]: one or more host config files
66 When encryption is enabled, each file is individually encrypted using Chacha20-Poly1305.
67 A unique counter stored at the start of the file. A (master) key must be provided by the application.
69 ## Exporting configuration
71 Calling `meshlink_export()` will return an array of host config files:
73 - arr[bin]: one or more host config files
75 ## Loading, saving and unloading configuration data to/from memory
77 ### Main configuration file
79 Created during first setup.
82 Might have to be saved again when port number or private key for invitations changes.
84 ### Host configuration files
86 Can be loaded partially into memory:
87 - devclass+blacklist status only, always required in memory, so loaded in `load_all_nodes()`.
88 - public key, needed whenever SPTPS is required, or when the application wants a fingerprint or verify signed data from that node.
89 - canonical and recent addresses, needed whenever we want to make outgoing connections to this node.
91 Furthermore, in order to properly merge new data, we need to load the whole config file into memory when:
92 - updating recent addresses
93 - exporting this node's information (no API for this yet)
95 Whenever a node's information is updated, we mark it dirty. It is written out at a convenient time.