> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/on-premise-active-directory-agent/service-management-and-troubleshooting.md).

# Service management and troubleshooting

### Service Management <a href="#service-management" id="service-management"></a>

#### Common Service Operations <a href="#common-service-operations" id="common-service-operations"></a>

**Check Service Status**:

```powershell
Get-Service -Name "BalkanIDADAgent"
```

**Start Service**:

```powershell
Start-Service -Name "BalkanIDADAgent"
```

**Stop Service**:

```powershell
Stop-Service -Name "BalkanIDADAgent" -Force
```

**Restart Service**:

```powershell
Restart-Service -Name "BalkanIDADAgent"
```

**View Service Details**:

```powershell
sc qc BalkanIDADAgent
sc query BalkanIDADAgent
```

#### Viewing Logs <a href="#viewing-logs" id="viewing-logs"></a>

**Application Logs** (per-day log files):

```powershell
# View latest log entries
Get-Content "C:\ProgramData\BalkanID\ad-agent\logs\*.log" -Tail 50

# Follow logs in real-time (PowerShell 7+)
Get-Content "C:\ProgramData\BalkanID\ad-agent\logs\*.log" -Wait -Tail 20
```

**Windows Event Log**:

```powershell
# View recent events
Get-EventLog -LogName Application -Source "BalkanIDADAgent" -Newest 10

# View all events
Get-EventLog -LogName Application -Source "BalkanIDADAgent"
```

#### Updating the Agent <a href="#updating-the-agent" id="updating-the-agent"></a>

The agent includes automatic update functionality:

1. **Check for Updates** (via TUI):
   * Launch TUI: `& "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --tui`
   * Press `U` or navigate to "Check for Updates"
   * Follow prompts to apply updates
2. **Manual Update**:
   * Re-run `install.ps1` to download and install the latest version
   * The installer will stop the service, update the binary, and restart the service

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Service Won't Start <a href="#service-wont-start" id="service-wont-start"></a>

1. **Check Event Log**:

   ```powershell
   Get-EventLog -LogName Application -Source "BalkanIDADAgent" -Newest 10
   ```
2. **Verify Configuration**:
   * Ensure `config.yaml` exists and is valid YAML
   * Check that all required fields are populated
   * Verify file permissions (service account needs read access)
3. **Test Configuration**:

   ```powershell
   # Launch TUI to test configuration
   & "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --configure
   ```

   * Navigate to "Test LDAP Connection"
   * Verify connection succeeds
4. **Check Service Account Permissions**:
   * Ensure the service account has appropriate AD permissions
   * Verify the service account password is correct

#### LDAP Connection Issues <a href="#ldap-connection-issues" id="ldap-connection-issues"></a>

1. **Verify Network Connectivity**:

   ```powershell
   Test-NetConnection -ComputerName "dc1.corp.example.com" -Port 636
   ```
2. **Test LDAP Connection Manually**:

   ```powershell
   # Using ldapsearch (if available)
   ldapsearch -H ldaps://dc1.corp.example.com:636 -x -D "CN=ADAgent,CN=Users,DC=corp,DC=example,DC=com" -w "password" -b "DC=corp,DC=example,DC=com" "(objectClass=user)"
   ```
3. **Check Firewall Rules**:
   * Ensure ports 389 (LDAP) or 636 (LDAPS) are open
   * Verify Windows Firewall allows outbound connections
4. **Verify Certificate** (for LDAPS):
   * Ensure the domain controller certificate is valid
   * Check certificate chain is trusted

#### Heartbeat Mode Issues <a href="#heartbeat-mode-issues" id="heartbeat-mode-issues"></a>

1. **Verify Credentials**:
   * Check `tenant_id`, `tenant_key`, `tenant_secret`, and `integration_id` in config
   * Ensure credentials are correct and not expired
2. **Test Network Connectivity**:

   ```powershell
   Test-NetConnection -ComputerName "api-integrators.app.balkan.id" -Port 443
   Test-NetConnection -ComputerName "app.balkan.id" -Port 443
   ```
3. **Check Logs**:

   ```powershell
   Get-Content "C:\ProgramData\BalkanID\ad-agent\logs\*.log" -Tail 100 
   ```

#### Configuration Issues <a href="#configuration-issues" id="configuration-issues"></a>

1. **Invalid YAML Syntax**:
   * Use a YAML validator to check syntax
   * Common issues: incorrect indentation, missing colons, unquoted special characters
2. **File Permissions**:
   * Ensure the service account can read `config.yaml`
   * Check file is not locked by another process
3. **Regenerate API Key**:
   * Launch TUI: `& "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --configure`
   * Navigate to "Regenerate API Key"
   * Save the new key securely

#### Update Issues <a href="#update-issues" id="update-issues"></a>

If automatic updates are not working:

1. **Verify Network Connectivity to Update Server**:

   ```powershell
   # Test connectivity to CloudFront CDN
   Test-NetConnection -ComputerName d3g543zyzzpcxb.cloudfront.net -Port 443

   # Test HTTPS access
   Invoke-WebRequest -Uri "https://d3g543zyzzpcxb.cloudfront.net/" -UseBasicParsing
   ```
2. **Check Firewall Rules**:
   * Ensure outbound HTTPS (port 443) traffic is allowed
   * Verify proxy settings if your network uses a proxy
   * Check if corporate firewall blocks CloudFront CDN
3. **Review Update Logs**:

   ```powershell
   Get-Content "C:\ProgramData\BalkanID\ad-agent\logs\*.log" | Select-String -Pattern "update|Update"
   ```
4. **Manual Update**:
   * If automatic updates fail, manually download and run `install.ps1` from the [official URL](https://d3g543zyzzpcxb.cloudfront.net/files/balkanid/ad-agent/latest/install.ps1)

***

### Additional Resources <a href="#additional-resources" id="additional-resources"></a>

* **Configuration File Location**: `C:\ProgramData\BalkanID\ad-agent\config.yaml`
* **Logs Directory**: `C:\ProgramData\BalkanID\ad-agent\logs\`
* **Executable Location**: `C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe`
* **Service Name**: `BalkanIDADAgent`

For additional support, please contact your BalkanID support


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/on-premise-active-directory-agent/service-management-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.