> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Golden Image Mode

> Prepare a Syteca Client golden image and enable Golden Image mode on the Application Server so cloned virtual machines don't create duplicate Client entries.

A **golden image** is a template virtual machine (VM) with a Syteca Client already installed, used to clone many identical VMs at once. Cloning a Client normally creates a duplicate Client entry for every clone, because each clone shares the same internal Client identifier. Golden Image mode solves this on both sides:

* On the **Client**, a one-time preparation step clears the identifier before the image is captured, so each clone generates its own identifier the first time it starts.
* On the **Application Server**, Golden Image mode automatically unassigns the license from a Client as soon as it goes offline, so licenses return to the pool for the next clone instead of piling up on VMs that no longer exist.

<Info>
  **Use this when:**

  * Deploying Syteca Clients through a VDI master image (VMware Horizon Composer, Citrix Provisioning Services, Hyper-V, AWS WorkSpaces).
  * Cloning a physical or virtual machine that already has a Syteca Client installed, for any reason.
  * Running floating endpoint licensing across virtual desktops, where licenses need to circulate automatically as desktops are created and destroyed.

  Pair it with [VDI monitoring](/docs/administration/deployment/vdi-monitoring) for the full picture of supported virtual desktop platforms, and with [Assign endpoint licenses](/docs/administration/licensing/assign-endpoint-licenses) for how floating licenses move between Clients.
</Info>

<Warning>
  These instructions apply to Syteca version 6.37 and later. On Windows Client agent versions older than **7.23.70**, a duplicate agent entry may still appear after the *first* deployment from a golden image; no further duplicates should occur after that. Agent version 7.23.70 and later avoids the issue entirely. Update the agent version in your templates to 7.23.70 or later before capturing a golden image.
</Warning>

## Configure the Client golden image

Do this once, on the Client machine that will become the golden image, before capturing the image.

<Steps>
  <Step title="Download the Client installation package">
    In the Management Tool, open the **Clients** page, click **Install Clients** (top right), then **Download Installation File**.
  </Step>

  <Step title="Select Windows and download">
    On the **Installation File Download** page, select **Windows**, then either **Windows Client installation Package (.ini+.exe)** to generate an installation package, or **Windows Client installation (.exe)** to download the installer directly.
  </Step>

  <Step title="Install the Client on the golden image machine">
    Copy the installation package or file to the computer that will serve as the golden image, and install the Client on it. See [Install Windows Clients locally](/docs/administration/clients/windows) for the installation procedure.
  </Step>

  <Step title="Rename the Client executable">
    On the golden image machine, open the Client installation folder (by default `C:\Program Files\Ekran System\Ekran System\Client`) and rename `EkranClient.exe` to `EkranClient1.exe`.
  </Step>

  <Step title="Stop the Client services">
    Open Windows Services and stop both the **EkranClient** and **EkranController** services.
  </Step>

  <Step title="Set the Golden Image registry value">
    Open Windows Registry Editor, go to `HKEY_LOCAL_MACHINE\SOFTWARE\EkranSystem\Client`, and:

    * Delete the **AgentGUID** value.
    * Add a new **DWORD** value named `GoldenImageMode` with data `1`.

    Save the changes.
  </Step>

  <Step title="Restore the Client executable name">
    Rename `EkranClient1.exe` back to `EkranClient.exe`.

    <Warning>
      Do not restart the **EkranClient** service after this step. It must stay stopped until the next system reboot — restarting it early gives the image a new ID and causes duplicates.
    </Warning>
  </Step>
</Steps>

Once these steps are complete, the image can be used to clone the virtual machine without creating duplicate Clients in the Management Tool.

<Frame caption="Selecting the Windows installation package on the Installation File Download page.">
  <img src="https://mintcdn.com/syteca/0FlD-vkHsBA1azVX/images/administration/clients/golden-image-installation-download.png?fit=max&auto=format&n=0FlD-vkHsBA1azVX&q=85&s=2b97cf0d4daf3f2d91014ad91664f5a2" alt="Installation File Download page with Windows operating system selected and installation package options" width="1895" height="850" data-path="images/administration/clients/golden-image-installation-download.png" />
</Frame>

### Automatically add cloned Clients to a Client group

Optionally, configure cloned Clients to join specific [Client groups](/docs/administration/clients/client-groups) automatically (in addition to the default **All Clients** group), so each clone inherits that group's settings immediately.

<Warning>
  **NOT AVAILABLE IN SAAS.** Since the `EkranServer.Settings.config` file isn't available in SaaS deployments, contact your Syteca vendor or the Syteca Support team to enable this behavior in a SaaS environment.
</Warning>

<Steps>
  <Step title="Enable auto-assignment">
    Add the following key to `EkranServer.settings.config` (located in `C:\Program Files\Ekran System\Ekran System\Server`):

    ```xml theme={"system"}
    <add key="ClientAutoAssignToClientGroupEnabled" value="1" />
    ```
  </Step>

  <Step title="Define the auto-assignment rule">
    Add a second key specifying the target Client group ID and the hostnames or IP addresses that should match it:

    ```xml theme={"system"}
    <add key="ClientAutoAssignToClientGroupWithId2" value="WIN11-COMP1; WIN11-COMP2; 192.168.90.10; 192.168.90.20"/>
    ```

    Find a Client group's ID on the **Clients** page, **Client Groups** tab, by clicking the group's name. To auto-assign to multiple groups, add one key per group, each with its own ID.

    <Tip>
      The value list accepts patterns as well as exact matches:

      * `192.168.1.*` matches every address starting with `192.168.1`.
      * `192.168.1.30-75` matches every address in that range.
      * `syteca-pc-*` matches every hostname starting with `syteca-pc-`.
    </Tip>
  </Step>

  <Step title="Restart the Application Server">
    Restart the **EkranServer** service to apply the changes.
  </Step>
</Steps>

A cloned Client whose hostname or IP address matches the rule is added automatically to the specified Client group and inherits all of that group's settings.

## Enable Golden Image mode on the Application Server

With Golden Image mode enabled on the Application Server, the server automatically unassigns a Client's license as soon as that Client goes offline — the mechanism that lets floating licenses circulate correctly across a fleet of cloned virtual desktops. See [Assign endpoint licenses](/docs/administration/licensing/overview#does-syteca-support-floating-licenses-whats-the-maximum-number-of-computers-one-license-can-monitor) for how this fits into the broader floating-licensing model.

<Warning>
  **NOT AVAILABLE IN SAAS.** Since the `EkranServer.Settings.config` file isn't available in SaaS deployments, contact your Syteca vendor or the Syteca Support team to enable this feature in a SaaS environment.
</Warning>

<Tabs>
  <Tab title="Version 6.53.1 and later">
    <Steps>
      <Step title="Stop the Application Server">
        Right-click the **Syteca Server** icon in the Windows System Tray and select **Stop**, or stop the **EkranServer** service from Task Manager.
      </Step>

      <Step title="Open the settings file">
        On the Application Server computer, open `EkranServer.Settings.config` (located in `C:\Program Files\Ekran System\Ekran System\Server`) in a text editor.
      </Step>

      <Step title="Add the Golden Image key">
        Add the following key:

        ```xml theme={"system"}
        <add key="GoldenImageMode" value="1" />
        ```

        Save the file.
      </Step>

      <Step title="Start the Application Server">
        Start the **EkranServer** service to resume normal operation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Versions before 6.53.1">
    <Steps>
      <Step title="Stop the Application Server">
        Right-click the **Syteca Server** icon in the Windows System Tray and select **Stop**, or stop the **EkranServer** service from Task Manager.
      </Step>

      <Step title="Set the registry value">
        Open Windows Registry Editor, select the `HKEY_LOCAL_MACHINE\SOFTWARE\EkranSystem` key, and add a new **DWORD (32-bit)** value named `GoldenImageMode` with data `1`.
      </Step>

      <Step title="Start the Application Server">
        Start the **EkranServer** service to resume normal operation.
      </Step>
    </Steps>

    <Note>
      After updating to version 6.53.1 or later, this setting moves from the registry to `EkranServer.Settings.config` automatically — existing values carry over, but further changes must be made in the config file.
    </Note>
  </Tab>
</Tabs>

## Alternative: unassign the license on virtual machine shutdown

If a golden image's master snapshot gets reused many times, Golden Image mode isn't the only way to avoid wasting licenses on machines that no longer exist — a shutdown script can unassign the license directly on the Client side instead.

<Warning>
  **NOT AVAILABLE IN SAAS.**
</Warning>

<Steps>
  <Step title="Create the uninstall script">
    Create a `.cmd` file (for example `uninstall_client.cmd`) containing:

    ```bat theme={"system"}
    call "<path_to_EkranClient.exe>" -uninstwl <uninstallation_key>
    ```

    For example:

    ```bat theme={"system"}
    call "C:\Progra~1\EkranS~1\EkranS~1\Client\EkranClient.exe" -uninstwl myuninstallkey
    ```
  </Step>

  <Step title="Turn on the virtual machine">
    Start the VM that will become the golden image.
  </Step>

  <Step title="Configure the system and install required software">
    Set up the machine as normal.
  </Step>

  <Step title="Install the Client with Protected mode disabled">
    Install the Syteca Client (remotely or locally) with **Enable Protected mode** deselected.
  </Step>

  <Step title="Clear the Client's AgentGUID">
    In Registry Editor, go to `HKEY_LOCAL_MACHINE\SOFTWARE\EkranSystem\Client`, right-click the **AgentGUID** value, and select **Delete**.
  </Step>

  <Step title="Copy the script to the VM">
    Copy `uninstall_client.cmd` to a target folder on the virtual machine.
  </Step>

  <Step title="Register the script as a shutdown script">
    Run `cmd.exe` as administrator, enter `gpedit`, and in the Local Group Policy Editor go to **Computer Configuration > Windows Settings > Scripts (Startup/Shutdown) > Shutdown**. Click **Add**, select `uninstall_client.cmd`, and click **OK**.
  </Step>

  <Step title="Create the master snapshot">
    The golden image is now ready.
  </Step>
</Steps>

From this point on, every VM started from this image connects to the Application Server as a new Client and gets a license assigned automatically. When the VM shuts down, the shutdown script runs and the license is unassigned.

<Note>
  To unassign the license on logoff instead of shutdown, configure the equivalent logoff script under **User Configuration > Windows Settings > Scripts (Logon/Logoff) > Logoff**.
</Note>

## Alternative: rename the hostname after cloning

For a one-off Windows VM clone rather than a repeatable golden image, a simpler manual fix avoids the full Golden Image mode setup above.

Every Windows Client gets a unique ID the first time it connects to the Application Server. Cloning a VM copies that ID along with it, so the clone can't connect until it looks different to the Application Server.

<Steps>
  <Step title="Rename the cloned VM">
    After cloning, change the VM's hostname.
  </Step>

  <Step title="Reboot">
    Restart the VM.
  </Step>

  <Step title="Confirm registration">
    Once it restarts, the Client registers as new, receives its own unique ID, and appears on the **Clients** page.
  </Step>
</Steps>

<Warning>
  Skipping the rename means the clone can't connect at all — the Application Server rejects it because a Client with that same hostname and ID already exists, and logs an error on the System Health page.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="VDI monitoring" icon="desktop" href="/docs/administration/deployment/vdi-monitoring">
    Supported virtual desktop platforms and floating-licensing patterns.
  </Card>

  <Card title="Assign endpoint licenses" icon="key" href="/docs/administration/licensing/assign-endpoint-licenses">
    How floating licenses circulate between Clients automatically.
  </Card>

  <Card title="Client groups" icon="users" href="/docs/administration/clients/client-groups">
    Group Clients to apply shared settings.
  </Card>

  <Card title="Windows Clients" icon="windows" href="/docs/administration/clients/windows">
    Installing and configuring Windows Clients.
  </Card>
</CardGroup>