src/dns-challenge-schema.README

   1 Introduction
   2 ------------
   3
   4 Promxox projects (PVE, PMG, PBS) all support ACME with DNS challenges.
   5 As there are many DNS providers we re-use the plugins for the great [acme.sh]
   6 project.
   7
   8 As a user interface needs to know which plugins there are supported we need to
   9 provide at least the list of known ones.
  10 But, we extend that and return a full JSON-Schema oriented Object Schema, so
  11 that any user-interface can use that to show UX hints and create the respective
  12 inputs for each plugin.
  13
  14 Note, we do not define a full schema for all plugins, but accept patches for
  15 adding one. See the [developer-documentation] about how to do so.
  16
  17 We use JSON as format as we need this schema in both, perl and rust based
  18 projects.
  19
  20 Schema Example
  21 --------------
  22
  23 A entry describing the data schema of a supported plugin could look like:
  24
  25 ```
  26 'dnsprovider' => {
  27     name => 'Full name of Plugin',
  28     fields => {
  29         'FOO_API_KEY' => {
  30             description => "The API key",
  31             default => "none",
  32             optional => 1,
  33             type => 'string',
  34         },
  35         ...
  36     },
  37 },
  38 ```
  39
  40 References
  41 ----------
  42
  43 [acme.sh]: https://acme.sh/
  44 [developer-documentation]: https://pve.proxmox.com/wiki/Developer_Documentation