Overview

Sometimes Kerio Control appliance encounters issues registering with AppManager as GFI Agent fails to install due to an error in the server configuration. In such cases you can find the corresponding error in the agent logs: 

[ERROR] ... failed to install agent. reason: failed to save appliance config. reason: error retrieving server endpoint: failed to load server configs: XML syntax error on line ...: invalid UTF-8

Such an error indicates an invalid character on the indicated line of the winroute.cfg file. This prevents the successful installation of the agent and the saving of the appliance configuration.

Solution

To resolve the issue of failing GFI AppManager installation due to an invalid UTF-8 character in the winroute.cfg file, follow these steps:

1. Download the winroute.cfg file (located at /opt/kerio/winroute/winroute.cfg) and open it with a text editor of your choice. We recommend an editor with syntax highlighting.
2. Navigate to the line indicated in the error message and check for any suspicious symbols. Many editors usually highlight non-UTF-8 characters, for example:
   
   

   Pay attention, sometimes there can be more than one character, like <variable name="Description">Skip al� other �iles</variable>!

3. Once you identified the character(s), edit the winroute.cfg on the appliance:
   1. Log in to the appliance via the console
   2. Stop agent (if the old version is there) with /etc/boxinit.d/70gfiagent stop
   3. (if connected from a local network) Stop winroute with /etc/boxinit.d/60winroute stop

      Beware - if you are on the console not from the local network (but from VPN or external SSH, for example), running this command may break your connectivity to the console!

   4. Edit the /opt/kerio/winroute/winroute.cfg and remove the invalid character or change it to UTF-8
   5. Save the changes and close the file
   6. (if stopped on step 3) Start winroute with /etc/boxinit.d/60winroute start
4. Once the file has been edited and saved, follow the steps in the article Resetting KerioControl’s connection to GFI AppManager.

Note: The registration process may take several hours to complete in some cases. Please be patient and allow it to finish.

Summary

The KerioControl appliance sometimes fails to register with the AppManager because the GFI Agent installation is blocked by an "invalid UTF-8" character error in the winroute.cfg file. To fix this issue, locate and correct the invalid character in the /opt/kerio/winroute/winroute.cfg. This involves identifying the problematic character, editing the file to correct or remove the character, and then restarting the necessary services on the appliance and Resetting KerioControl’s connection to GFI AppManager.

FAQ

1. How do I locate the invalid UTF-8 character in the winroute.cfg file?
   Open the winroute.cfg file using a text editor that supports syntax highlighting. Navigate to the line number indicated in the error message. The editors usually highlight any non-UTF-8 characters, making them easier to identify.
2. What steps should I take to correct the invalid UTF-8 character in the winroute.cfg file?
   First, stop the agent and winroute services on the appliance. Next, edit the winroute.cfg file to remove or replace the invalid character with a valid UTF-8 character. Save the file and restart the stopped winroute service.
3. What should I do after correcting the winroute.cfg file to ensure the appliance registers successfully with GFI AppManager?
   After winroute.cfg file is fixed and the winroute service restarted, follow the steps to reset KerioControl's connection to GFI AppManager, as outlined in the support article. Allow several hours for the registration process to complete.