# Crayonic Agent – Cloud Sync Configuration (AD/GPO Deployment Guide)

This guide explains how to deploy the Windows service agent with different Cloud Sync configurations in Active Directory environments, and how to manage the setting via Group Policy or PowerShell.

Important scope note:
- Cloud Sync controls the agent's data egress to the backend (event uploads).
- Cloud Sync does not affect Bridge operations, Badge functionality, or Agent update channels. Those continue to function independently.

## Deliverables
Single MSI with configurable Cloud Sync settings:
- MSI Package: `CrayonicAgent_x64_1.0.205.msi`
- Cloud Sync configuration controlled via msiexec command-line parameters
- Transform (MST) for disabling Cloud Sync: `CrayonicAgent_x64_1.0.205_CloudSyncDisabled.mst`


## Installation Options

### Command-line Parameters
- **CLOUDSYNCENABLED**: Set to 0 to disable Cloud Sync, 1 to enable (default: 1)
- **CLOUDSYNCURL**: Optional custom URL for Cloud Sync endpoint

### Installation Examples
```batch
# Cloud Sync Enabled (default)
msiexec /i "CrayonicAgent_x64_1.0.205.msi" /qn

# Cloud Sync Disabled
msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCENABLED=0 /qn

# Custom Cloud Sync URL
msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCURL=https://custom.endpoint.com /qn
### Using the MST
If you have the transform (MST), apply it during installation to force Cloud Sync off without needing parameters:
```
msiexec /i "CrayonicAgent_x64_1.0.205.msi" TRANSFORMS="CrayonicAgent_x64_1.0.205_CloudSyncDisabled.mst" /qn
```



# Both disabled and custom URL
msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCENABLED=0 CLOUDSYNCURL=https://internal.company.com /qn
```

## Policy and precedence
The agent evaluates the registry in this order (highest precedence first):
1) HKLM\SOFTWARE\Policies\Crayonic\Agent
   - `CloudSyncEnabled` (DWORD) 1/0 — Enable Cloud Sync
   - `CloudSyncUrl` (REG_SZ) — Optional URL override
   - `LogLevel` (REG_SZ) — Logging level (INFO, DEBUG, ERROR, etc.)
2) HKLM\SOFTWARE\Crayonic\Agent (local fallback set by the MSI)
   - `CloudSyncEnabled` (DWORD)
   - `CloudSyncUrl` (REG_SZ)
   - `LogLevel` (REG_SZ)

Notes:
- The MSI parameters set the default values in the local fallback registry.
- The MSI does not write to the Policies hive; that hive is reserved for enterprise policy (GPO/MDM).
- The registry component is authored with NeverOverwrite so repairs/upgrades will not flip admin-set values.

## Install via Active Directory (GPO)
Prerequisites:
- Place the MSI on a UNC share accessible by computer accounts (e.g., `\\fileserver\software\Crayonic\`).
- Ensure Domain Computers have Read access to the share.

Steps:
1) Open Group Policy Management Console (GPMC).
2) Create or edit a GPO linked to the target OU.
3) Navigate to: Computer Configuration → Policies → Software Settings → Software installation.
4) Right‑click → New → Package…
   - Select `CrayonicAgent_x64_1.0.205.msi` via UNC path
### GPO with MST
- In the package Properties → Modifications tab, Add the MST: `CrayonicAgent_x64_1.0.205_CloudSyncDisabled.mst`.
- Ensure the MSI and MST are both referenced via UNC paths and remain in place.
- This approach avoids needing to add `CLOUDSYNCENABLED=0` as a parameter and is less error-prone.

   - Do not use mapped drives.
   - Choose “Advanced” deployment.
5) In the package Properties:
   - Preferred: use the MST generated by build: `CrayonicAgent_x64_1.0.205_CloudSyncDisabled.mst`
     - Properties → Modifications tab → Add the MST file.
   - Alternative (no MST): use command-line parameters in the Deployment tab’s Install properties
     - For Cloud Sync disabled: `CLOUDSYNCENABLED=0`
     - For custom URL: `CLOUDSYNCURL=https://your.endpoint.com`
   - Deployment tab → Deployment type: Assigned.
   - Upgrades tab → Configure to upgrade previous versions (same UpgradeCode), if applicable.
6) Apply the GPO. The agent will install at the next startup or GP refresh.

### GPO Examples for Different OUs
- **Sales OU**: No parameters (Cloud Sync enabled by default)
- **Finance OU**: `CLOUDSYNCENABLED=0` (Cloud Sync disabled)
- **IT OU**: `CLOUDSYNCURL=https://internal.company.com` (Custom endpoint)

Verification:
- Registry (effective policy):
  - Check `HKLM\SOFTWARE\Policies\Crayonic\Agent\CloudSyncEnabled` (if set)
  - Else check `HKLM\SOFTWARE\Crayonic\Agent\CloudSyncEnabled`
- Service logs should contain: "Cloud Sync disabled by policy" when disabled.

## Install via SCCM/MECM (optional)
- Create an Application → MSI deployment type.
- Installation program examples:
  - Cloud Sync enabled: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" /qn`
  - Cloud Sync disabled: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCENABLED=0 /qn`
  - Custom URL: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCURL=https://custom.url /qn`
- Detection method: MSI ProductCode (recommended).

## Install via Intune (optional)
- Use a Win32 app (IntuneWin) containing the MSI.
- Install command examples:
  - Cloud Sync enabled: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" /qn`
  - Cloud Sync disabled: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCENABLED=0 /qn`
  - Custom URL: `msiexec /i "CrayonicAgent_x64_1.0.205.msi" CLOUDSYNCURL=https://custom.url /qn`
- Detection: MSI ProductCode.

## Configure via PowerShell
Enterprise enforcement (Policies hive):
```
New-Item -Path 'HKLM:\SOFTWARE\Policies\Crayonic\Agent' -Force | Out-Null
New-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Crayonic\Agent' -Name 'CloudSyncEnabled' -PropertyType DWord -Value 0 -Force | Out-Null
# Optional URL override
New-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Crayonic\Agent' -Name 'CloudSyncUrl' -PropertyType String -Value 'https://your-endpoint.example' -Force | Out-Null
```

Local fallback (not recommended for enterprise enforcement):
```
New-Item -Path 'HKLM:\SOFTWARE\Crayonic\Agent' -Force | Out-Null
New-ItemProperty -Path 'HKLM:\SOFTWARE\Crayonic\Agent' -Name 'CloudSyncEnabled' -PropertyType DWord -Value 0 -Force | Out-Null
# Optional URL override
New-ItemProperty -Path 'HKLM:\SOFTWARE\Crayonic\Agent' -Name 'CloudSyncUrl' -PropertyType String -Value 'https://your-endpoint.example' -Force | Out-Null
```

## Repair and upgrade behavior
- The local registry component is authored with `NeverOverwrite="yes"` and a stable Component GUID so that repairs and upgrades do not flip existing values.
- Recommended (and commonly used): `Permanent="yes"` so the local setting survives uninstalls/major upgrades.
- Policies hive always overrides local values.

## Troubleshooting
- GPO: MSI paths must be UNC and accessible to computer accounts; do not move/rename files after deploying the policy.
- GPO: Verify command-line parameters are correctly set in the Modifications tab of the package properties.
- Review Windows Event Log → Application (MsiInstaller) for deployment results.
- For manual installs, collect logs with `/l*v C:\Temp\crayonic_install.log`.
- If Cloud Sync appears enabled despite MST: verify the MST was applied (GPO Transforms tab) and that a conflicting Policies value isn’t forcing enable.

## Security considerations
- Standard users can read HKLM; writing requires admin/GPO.
- Policies hive is preferred for compliance; manage it via Group Policy or MDM.

## FAQ
- Q: Does disabling Cloud Sync affect Bridge, Badge, or Agent updates?
  - A: No. Those channels are independent and not controlled by the Cloud Sync setting.
- Q: Can we enforce the setting centrally?
  - A: Yes. Set `CloudSyncEnabled` under `HKLM\SOFTWARE\Policies\Crayonic\Agent` via Group Policy Preferences or MDM.
- Q: What if we upgrade later without the MST?
  - A: With `NeverOverwrite` and (optionally) `Permanent`, existing settings remain intact. Policies hive, if configured, always wins.