Active Directory Watch Daemon¶

The Active Directory Watch Daemon (or adwatchd) is a Windows application geared towards automating the manual process of incrementing the version stanza of a GPT.ini file.

At its core, the program can be simplified to the following steps:

watch a list of user-configured directories for changes – subdirectories are also watched, but only the root directory will have a GPT.ini file
when a change is detected, attempt to locate a GPT.ini file at the root of the watched directory, or create one if absent
if a GPT.ini file is found, increment the version stanza of the file by 1, thus signalling clients that a new version of the assets (including scripts) are available to download during the next client refresh

Installation¶

The adwatchd executable is available as a standalone Windows executable file, distributed as part of the adsys-windows Ubuntu package, or packaged as an installer available on the GitHub repository.

Installing via the Ubuntu package¶

To source the adwatchd executable from the adsys-windows Ubuntu package, we must run the following (on Ubuntu):

sudo apt install adsys-windows

After a successful installation, the adwatchd.exe executable will be available in the /usr/share/adsys/windows directory. We suggest you deploy this executable to a persistent directory of your choosing on the AD Domain Controller, such as %SystemDrive%\Program Files\Ubuntu\adsys\.

Installing via the bespoke installer¶

Download the latest release of the adwatchd_setup.exe file (or a specific version if you wish), and run it.

Follow the installation steps, paying attention to the prompts, optionally specifying a different installation directory for the application.

Configuring and starting the daemon¶

Regardless of how the application is installed, the configuration steps are the same:

locate and run the adwatchd.exe executable to start the application’s interactive configuration tool
specify a path for the configuration file, or leave it blank to use the default location (the directory where the executable is located)
specify a list of directories to watch, one per line (the program will block installation if any of the directories do not exist)
hit the [ Install ] button to finish the installation, this will:
- create the configuration file if it does not exist
- install and start the adwatchd Windows service

For a better understanding on what directories should be configured for watching, please refer to the Installing scripts on sysvol section of the [Scripts execution](../explanation/scripts#Installing scripts on sysvol) document.

Note that the interactive configuration tool can only be run if the adwatchd service is not already installed on the machine. Please refer to the [CLI usage](#CLI usage) section for instructions on how to finely manage the service.

We recommend making use of the interactive configuration tool to install the application, as it provides a level of error handling, taking care of path normalisation and the creation of the configuration file.

The configuration file is stored as a YAML file, and can be freely edited after the application has been installed. The following keys are configurable:

verbose: 0     # 0 = warning, 1 = info, 2 = debug, 3 = debug with caller output
dirs:          # list of directories to watch
  - C:\Windows\SYSVOL\sysvol\testdomain.com\Ubuntu     # traditional path
  - \\testdomain.com\SYSVOL\testdomain.com\Ubuntu      # UNC path

Configuring the service using a pre-filled configuration file¶

For convenience, the adwatchd application can be configured with a pre-filled configuration file. Start a Command Prompt or PowerShell window and run one of the following:

REM Run the interactive configuration tool with a predefined configuration file
REM
REM This will start the interactive configuration tool with pre-filled entries for the
REM config path and directories to watch, leaving the user to press the [ Install ] button
C:\path\to\adwatchd.exe -c path\to\config.yaml

REM Run the service installation command with a predefined configuration file
REM
REM This will install the service with the given configuration file and start it
C:\path\to\adwatchd.exe service install -c path\to\config.yaml

Upgrading¶

The upgrade process differs based on the installation method used. If you decide to switch to a different installation method, you will need to uninstall the existing service beforehand.

Upgrading via the Ubuntu package¶

Source the new adwatchd executable from the adsys-windows Ubuntu package
Stop the adwatchd service (via the Services GUI or the adwatchd service stop command)
(Optional) Remove the existing adwatchd service from the system (through the adwatchd service uninstall command)
Replace the existing adwatchd.exe executable with the new one
(Optional) Install the adwatchd service (through the adwatchd service install command)
Start the adwatchd service (via the Services GUI or the adwatchd service start command)

The optional steps are only necessary if the intent is to do a complete upgrade of the application and are not usually needed. Always refer to the changelog for information on the latest version of the application.

Upgrading via the bespoke installer¶

Source the latest release of the adwatchd_setup.exe file
Run the installer, following the prompts

The installer will automatically take care of the upgrade process, and will offer to stop the service if it is running prior to the upgrade, and start it afterwards.