github.com/teknogeek/dnscontrol@v0.2.8/providers/activedir/doc.md (about)

     1  ### ActiveDirectory
     2  
     3  This provider updates a DNS Zone in an ActiveDirectory Integrated Zone.
     4  
     5  When run on Windows, AD is updated directly. The code generates
     6  PowerShell commands, executes them, and checks the results.
     7  It leaves behind a log file of the commands that were generated.
     8  
     9  When run on non-Windows, AD isn't updated because we can't execute
    10  PowerShell at this time.  Instead of reading the existing zone data
    11  from AD, It learns what
    12  records are in the zone by reading
    13  `adzonedump.{ZONENAME}.json`, a file that must be created beforehand.
    14  It does not actually update AD, it generates a file with PowerShell
    15  commands that would do the updates, which you must execute afterwords.
    16  If the `adzonedump.{ZONENAME}.json` does not exist, the zone is quietly skipped.
    17  
    18  Not implemented:
    19  
    20  * Delete records.  This provider will not delete any records. It will only add
    21  and change existing records. See "Note to future devs" below.
    22  * Update TTLs.  It ignores TTLs.
    23  
    24  
    25  ## required creds.json config
    26  
    27  No "creds.json" configuration is expected.
    28  
    29  ## example dns config js:
    30  
    31  ```
    32  var REG_NONE = NewRegistrar('none', 'NONE')
    33  var DSP_ACTIVEDIRECTORY_DS = NewDSP("activedir", "ACTIVEDIRECTORY_PS");
    34  
    35  D('ds.stackexchange.com', REG_NONE,
    36      DSP_ACTIVEDIRECTORY_DS,
    37  )
    38  
    39  
    40      // records handled by another provider...
    41  );
    42  ```
    43  
    44  ## Special Windows stuff
    45  
    46  This provider needs to do 2 things:
    47  
    48  * Get a list of zone records:
    49    * powerShellDump: Runs a PS command that dumps the zone to JSON.
    50    * readZoneDump: Opens a adzonedump.$DOMAINNAME.json file and reads JSON out of it.  If the file does not exist, this is considered an error and processing stops.
    51  
    52  * Update records:
    53    * powerShellExec: Execute PS commands that do the update.
    54    * powerShellRecord: Record the PS command that can be run later to do the updates.  This file is -psout=dns_update_commands.ps1
    55  
    56  So what happens when?  Well, that's complex.  We want both Windows and Linux to be able to use -fakewindows
    57  for either debugging or (on Windows) actual use.  However only Windows permits -fakewinows=false and actually executes
    58  the PS code.  Here's which algorithm is used for each case:
    59  
    60    * If -fakewindows is used on any system: readZoneDump and powerShellRecord is used.
    61    * On Windows (without -fakewindows): powerShellDump and powerShellExec is used.
    62    * On Linux (wihtout -fakewindows): the provider loads as "NONE" and nothing happens.
    63  
    64  
    65  ## Note to future devs
    66  
    67  ### Why doesn't this provider delete records?
    68  
    69  Because at this time Stack doesn't fully control AD zones
    70  using dnscontrol. It only needs to add/change records.
    71  
    72  What should we do when it does need to delete them?
    73  
    74  Currently NO_PURGE is a no-op.  I would change it to update
    75  domain metadata to flag that deletes should be enabled/disabled.
    76  Then generate the deletes only if this flag exists.  To be paranoid,
    77  the func that does the deleting could check this flag to make sure
    78  that it really should be deleting something.