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 - str: name of the submesh this node is part of, or "." if it's in the core mesh
  47 - int32: device class
  48 - bool: blacklisted
  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
  52
  53 ## Invitation files
  54
  55 When stored on disk, there is one file per pending invitation, inside the directory `invitations/`.
  56 The contents of an invitation file are:
  57
  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
  63
  64 ## Encryption
  65
  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.
  68
  69 ## Exporting configuration
  70
  71 Calling `meshlink_export()` will return an array of host config files:
  72
  73 - arr[bin]: one or more host config files
  74
  75 ## Loading, saving and unloading configuration data to/from memory
  76
  77 ### Main configuration file
  78
  79 Created during first setup.
  80 Loaded at start.
  81 Never unloaded.
  82 Might have to be saved again when port number or private key for invitations changes.
  83
  84 ### Host configuration files
  85
  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.
  90
  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)
  94
  95 Whenever a node's information is updated, we mark it dirty. It is written out at a convenient time.
  96
  97