exec.toml raw

   1  Name = "External program"
   2  Description = "Solving the DNS-01 challenge using an external program."
   3  URL = "/dns/exec"
   4  Code = "exec"
   5  Since = "v0.5.0"
   6  
   7  Example = '''
   8  EXEC_PATH=/the/path/to/myscript.sh \
   9  lego --dns exec -d '*.example.com' -d example.com run
  10  '''
  11  
  12  Additional = '''
  13  
  14  ## Base Configuration
  15  
  16  | Environment Variable Name | Description                           |
  17  |---------------------------|---------------------------------------|
  18  | `EXEC_MODE`               | `RAW`, none                           |
  19  | `EXEC_PATH`               | The path of the the external program. |
  20  
  21  
  22  ## Additional Configuration
  23  
  24  | Environment Variable Name  | Description                                                        |
  25  |----------------------------|--------------------------------------------------------------------|
  26  | `EXEC_POLLING_INTERVAL`    | Time between DNS propagation check in seconds (Default: 3).        |
  27  | `EXEC_PROPAGATION_TIMEOUT` | Maximum waiting time for DNS propagation in seconds (Default: 60). |
  28  | `EXEC_SEQUENCE_INTERVAL`   | Time between sequential requests in seconds (Default: 60).         |
  29  
  30  
  31  ## Description
  32  
  33  The file name of the external program is specified in the environment variable `EXEC_PATH`.
  34  
  35  When it is run by lego, three command-line parameters are passed to it:
  36  The action ("present" or "cleanup"), the fully-qualified domain name and the value for the record.
  37  
  38  For example, requesting a certificate for the domain 'my.example.org' can be achieved by calling lego as follows:
  39  
  40  ```bash
  41  EXEC_PATH=./update-dns.sh \
  42  lego --dns exec --d my.example.org run
  43  ```
  44  
  45  It will then call the program './update-dns.sh' with like this:
  46  
  47  ```bash
  48  ./update-dns.sh "present" "_acme-challenge.my.example.org." "MsijOYZxqyjGnFGwhjrhfg-Xgbl5r68WPda0J9EgqqI"
  49  ```
  50  
  51  The program then needs to make sure the record is inserted.
  52  When it returns an error via a non-zero exit code, lego aborts.
  53  
  54  When the record is to be removed again,
  55  the program is called with the first command-line parameter set to `cleanup` instead of `present`.
  56  
  57  If you want to use the raw domain, token, and keyAuth values with your program, you can set `EXEC_MODE=RAW`:
  58  
  59  ```bash
  60  EXEC_MODE=RAW \
  61  EXEC_PATH=./update-dns.sh \
  62  lego --dns exec -d my.example.org run
  63  ```
  64  
  65  It will then call the program `./update-dns.sh` like this:
  66  
  67  ```bash
  68  ./update-dns.sh "present" "--" "my.example.org." "some-token" "KxAy-J3NwUmg9ZQuM-gP_Mq1nStaYSaP9tYQs5_-YsE.ksT-qywTd8058G-SHHWA3RAN72Pr0yWtPYmmY5UBpQ8"
  69  ```
  70  
  71  ## Commands
  72  
  73  {{% notice note %}}
  74  The `--` is because the token MAY start with a `-`, and the called program may try and interpret a `-` as indicating a flag.
  75  In the case of urfave, which is commonly used,
  76  you can use the `--` delimiter to specify the start of positional arguments, and handle such a string safely.
  77  {{% /notice %}}
  78  
  79  ### Present
  80  
  81  | Mode    | Command                                            |
  82  |---------|----------------------------------------------------|
  83  | default | `myprogram present <FQDN> <record>`                |
  84  | `RAW`   | `myprogram present -- <domain> <token> <key_auth>` |
  85  
  86  ### Cleanup
  87  
  88  | Mode    | Command                                            |
  89  |---------|----------------------------------------------------|
  90  | default | `myprogram cleanup <FQDN> <record>`                |
  91  | `RAW`   | `myprogram cleanup -- <domain> <token> <key_auth>` |
  92  
  93  '''
  94