git.meshlink.io Git - meshlink/blob - doc/Configuration.md

   1 # Configuration files
   2
   3 There currently are three different types of configuration files in MeshLink:
   4
   5 - the main configuration file
   6 - the host config files
   7 - pending invitation files
   8
   9 All configuration files are in PackMessage format. The contents will be
  10 described below.
  11
  12 There are three different ways envisioned to store configuration data:
  13
  14 - unencrypted files
  15 - encrypted files
  16 - ephemeral, in-memory storage
  17
  18 To keep things as simple and flexible as possible, there are some restrictions:
  19
  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.
  26
  27 ## Main configuration file
  28
  29 When stored on disk, it's in `meshlink.conf`. The contents are:
  30
  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
  36
  37 More information about the local node is stored in its host config file.
  38
  39 ## Host configuration files
  40
  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:
  43
  44 - uint32: configuration format version
  45 - str: name of the node
  46 - int32: device class
  47 - bool: blacklisted
  48 - bin: public Ed25519 key
  49 - str: canonical address (may be zero length if unset)
  50 - arr[ext]: recent addresses
  51
  52 ## Invitation files
  53
  54 When stored on disk, there is one file per pending invitation, inside the directory `invitations/`.
  55 The contents of an invitation file are:
  56
  57 - uint32: invitation format version
  58 - str: name of the invitee
  59 - int32: device class of the invitee (may be unused)
  60 - arr[bin]: one or more host config files
  61
  62 ## Encryption
  63
  64 When encryption is enabled, each file is individually encrypted using Chacha20-Poly1305.
  65 A unique counter stored at the start of the file. A (master) key must be provided by the application.
  66
  67 ## Exporting configuration
  68
  69 Calling `meshlink_export()` will return an array of host config files:
  70
  71 - arr[bin]: one or more host config files
  72
  73 ## Loading, saving and unloading configuration data to/from memory
  74
  75 ### Main configuration file
  76
  77 Created during first setup.
  78 Loaded at start.
  79 Never unloaded.
  80 Might have to be saved again when port number or private key for invitations changes.
  81
  82 ### Host configuration files
  83
  84 Can be loaded partially into memory:
  85 - devclass+blacklist status only, always required in memory, so loaded in `load_all_nodes()`.
  86 - public key, needed whenever SPTPS is required, or when the application wants a fingerprint or verify signed data from that node.
  87 - canonical and recent addresses, needed whenever we want to make outgoing connections to this node.
  88
  89 Furthermore, in order to properly merge new data, we need to load the whole config file into memory when:
  90 - updating recent addresses
  91 - exporting this node's information (no API for this yet)
  92
  93 Whenever a node's information is updated, we mark it dirty. It is written out at a convenient time.
  94
  95