Service management and troubleshooting

Service Management

Common Service Operations

Check Service Status:

Get-Service -Name "BalkanIDADAgent"

Start Service:

Start-Service -Name "BalkanIDADAgent"

Stop Service:

Stop-Service -Name "BalkanIDADAgent" -Force

Restart Service:

Restart-Service -Name "BalkanIDADAgent"

View Service Details:

sc qc BalkanIDADAgent
sc query BalkanIDADAgent

Viewing Logs

Application Logs (per-day log files):

# 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:

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

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

Updating the Agent

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

Service Won't Start

1. Check Event Log:

   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:

   # 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

1. Verify Network Connectivity:

   Test-NetConnection -ComputerName "dc1.corp.example.com" -Port 636

2. Test LDAP Connection Manually:

   # 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

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:

   Test-NetConnection -ComputerName "api-integrators.app.balkan.id" -Port 443
   Test-NetConnection -ComputerName "app.balkan.id" -Port 443

3. Check Logs:

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

Configuration Issues

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

If automatic updates are not working:

1. Verify Network Connectivity to Update Server:

   # 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:

   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

---

Additional Resources

• 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