Agent Toubleshooting Default

Introduction

In this section, we can find some of the most common errors related to the Agent and where we can find the different configuration files, logs, etc. in the different operating systems.

App Settings Service file

In the appsettings.json file, we can find all the configuration related to the agent Service configuration (OSQueries,WireGuard Vpn Configuration, etc.) that has been retrieved from the OpenNAC Enterprise server.

• Windows

"C:\Program Files\OpenCloudFactory\OpenNAC Agent\OpenNACService\config\appsettings.json"

• Mac

/Library/com.opencloudfactory.opennacagent/config/appsettings.json

• Linux

/opt/opencloudfactory/opencloudfactory.agent.service/config/appsettings.json

App Settings UI file

In the appsettings.json file we can find all the configuration related to the agent UI configuration (Use wireguard, Use SAML, Language, Welcome URL, etc.) that has been retrieved from the OpenNAC Enterprise server.

• Windows

"C:\Program Files\OpenCloudFactory\OpenNAC Agent\OpenNAC UI Console\config\appsettings.json"

• Mac

/Applications/OpenNACAgent.app/Contents/MacOS/config/appsettings.json

• Linux

/opt/opencloudfactory/opencloudfactory.agent.ui/config/appsettings.json

VPN configuration file

In the following paths, we can find the VPN configuration files, for Wireguard and OpenVPN, that the Agent retrieves from the OpenNAC Enterprise server. If we could not retrieve it correctly from the server or detect if we have any error in the file parameters, checking for file errors would be helpful.

Wireguard

• Windows

C:\Program Files\OpenCloudFactory\OpenNAC Agent\OpenNACService\wireguard

• Mac

/Library/com.opencloudfactory.opennacagent/wireguard

• Linux

/opt/opencloudfactory/opencloudfactory.agent.service.linux/wireguard

OpenVPN

• Windows

C:\Program Files\OpenCloudFactory\OpenNAC Agent\OpenNACService\openvpn

• Mac

/Library/com.opencloudfactory.opennacagent/openvpn

• Linux

/opt/opencloudfactory/opencloudfactory.agent.service.linux/openvpn

OpenNAC Service logs

In this section, we will find the paths of the different logs related to the execution of the OpenNAC Agent. In these logs, we can detect service execution errors, see the processes that are executed, see the information collected by the agent service, the payload sent by the agent to the server, etc.

• Windows

C:\ProgramData\OpenCloudFactory\OpenNAC Agent\OpenNACService\Logs\OpenCloudFactory.Agent.Service.Windows.log

• Mac

/Library/Logs/OpenCloudFactory/OpenNAC Agent/OpenNACService/Logs/OpenCloudFactory.Agent.Service.Osx.log

• Linux

/var/log/OpenCloudFactory/OpenNAC Agent/OpenNACService/Logs/OpenCloudFactory.Agent.Service.Linux.log

UI Application logs

In this section, we will find the paths of the different logs related to the execution of the UI part of the OpenNAC Enterprise solution. We will be able to see if we have had any error regarding the application view, connections to the VPN, etc.

• Windows

C:\Users\AppData\Local\OpenCloudFactory\OpenNAC Agent\OpenNAC UI Console\Logs\OpenCloudFactory.Agent.UI.log

• Mac

/home/.local/share/OpenCloudFactory/OpenNAC Agent/OpenNAC UI Console/Logs/OpenCloudFactory.Agent.UI.log

• Linux

/Users/.local/share/OpenCloudFactory/OpenNAC Agent/OpenNAC UI Console/Logs/OpenCloudFactory.Agent.UI.log

Log content

This section presents warning and error logs for different cases:

1. The WireGuard configuration file includes a parameter that cannot be replaced as it has not been returned by the server. This results in an error log and the WireGuard connection process is unable to finalize. The error log reads:

Failed to replace all parameters in the WireGuard configuration file. There are still parameters to replace.

2. The server response to the WireGuard disconnect is unexpected. If the response is not a valid JSON or not an expected JSON object, the following warning log is displayed:

Cannot deserialize WireGuardResponse. Probably server not return a valid json. MAC={macAddressUsedToConnectBefore}"

3. The handshake timeout is reached after opening the interface, probably due to a misconfiguration. Log of type warning in service log:

Unable to establish handshake connection with VPN server.

User Interface error message in the WireGuard VPN window:

Connection with the VPN server could not be established.

4. When there is an empty parameter in the WireGuard VPN configuration file, the WireGuard connection process finalizes, and the error log reads:

An empty parameter has been detected in the WireGuard configuration file. Parameter: {parameter}.

Example of parameter="wireGuardDnsServer"

5. The application generates a warning when it receives a WireGuard parameter from the server that is not listed as a possible value in the appsettings.json file. The warning log reads:

A parameter has been received from the server which is not defined as a wireguard replacement parameter in the appsettings. Parameter Key: {wireGuardParameterKey}.

Example wireGuardParameterKey="wireGuardAllowedIps"

6. The WireGuard .nac file, which is in JSON format, cannot be deserialized due to unexpected content within the file. This results in an error log that reads:

The information in the file could not be read. It seems that it is not a valid json format.

7. Attempting to create a WireGuard tunnel, both the wg-quick up command for macOS and Linux and the creation of a tunnel service for Windows have failed.This generates a warning log that reads:

A problem has occurred when lifting the WireGuard tunnel. It seems that it is not possible to set up the tunnel.

8. Although the wg-quick-up command for macOS and Linux and the creation of a tunnel service for Windows returned successfully, the state of the WireGuard interface does not provide any information (empty WireGuard command output). It generates a warning log that reads:

Unable to open WireGuard interface.

WireGuard debug logs:

Sending wg connect to endpoint: {endpoint}. IP: {ip}. MAC: {mac}. FarmId: {farmId}

Sending wg disconnect to endpoint: {endpoint}. IP: {ip}. MAC: {mac}. FarmId: {farmId}"

9. When a parameter returned by the server (for example wireGuardPrivateKey) is empty, it generates a debug log that reads:

An empty parameter has been received from the server. It is not possible to initiate a connection to WireGuard. Parameter Key: {key}

When connecting through Wireguard SAML, the “OpenCloudFactory: config” service is created for a brief period, but it is removed from the list of Windows Services once the user interface shows Disconnected.

Log format

Logs can be of type TRACE, WARNING, INFO, DEBUG, ERROR or EXCEPTION. If the debug option is enabled on Agent profile, the Agent will print debug lines in log file.

The log format is: [ LOG DATE IN UTC | LOG TYPE| CODE CLASS| CLASS METHOD| MESSAGE ]

Log example:

2021-06-25T09:59:58Z | INFO | BackgroundServiceBase | SaveOpennacServerRequestedCallback | User wanted to configure the server(s): https://ocfcorp.opencloudfactory.com

2021-06-25T09:59:59Z | INFO | BackgroundServiceBase | SaveOpennacServerRequestedCallback | Server was successfully configured

Enabling debug mode will record more information in the logs stored by the Agent application.

To activate Debug option, go to the OpenNAC Enterprise Administration portal and open the ON Agent -> Agent Profiles option. Edit the corresponding Agent profile and enable the Debug mode option.

In the Service configuration section, we will need to enable the Debug mode flag.

In the Taskbar configuration section, we will also need to enable the Debug mode flag.

For further information, check the documentation about the Agent Profile.

Agent User Interface Messages

This table presents warnings, notifications, errors and status change messages that may be displayed on the client’s machine along with their respective contexts.

UI message	Context
Invalid 2FA code.	2FA
The user specified does not have the 2FA configured.	2FA
2FA is required for the specified user.	2FA
Please enter the 2FA code.	2FA
OpenNAC Agent is updating	Agent update
The new agent version could not be installed. The package is probably corrupt.	Agent update
Please select a configuration file.	Configuration File
The config file name contains characters that are nonalphabetic and have no digits.	Configuration File
The configuration file does not exist.	Configuration File
Invalid IPv4 format.	Configuration File
Unknown host(s), it should be ipv4, ipv6, or domain.	Configuration File
Unknown host(s), it should be ipv4, ipv6, or domain.	Configuration File
Invalid credentials	Credentials
Invalid username or password.	Credentials
Please fill in all the fields.	Credentials
Whitespaces are not allowed.	Credentials
No payload has been sent.	Payload
Doesn’t match any policy yet.	Policy
It was not possible to run the script because impersonation is enabled and no user is logged on to the machine.	Script
There are no available servers.	Servers
Not connected to a server. Please configure it on the About OpenNAC Agent window.	Servers
There are no available servers. Cannot open the URL.	Servers
The VPN server is not responding.	Servers
Could not disconnect the user from the server.	Servers
Unable to connect to a server, please configure one or more below.	Servers
An active server for the Agent was not detected.	Servers
Successfully changed opennac server.	Servers
The server list contains characters that are nonalphabetic and have no digits.	Servers
The server list cannot be empty.	Servers
Unable to connect with OpenNAC Service. Check if it is running.	Servers
Please select the server protocol.	Servers
You must select the server protocol, not type it.	Servers
Please write your server IP/s or domain/s	Servers
Timeout exceeded. Please try again.	Timeout
Process canceled due to window closing.	UI
Only authenticated agents can send data to the opennac server.	User Authentication
Request denied.	User Authentication
Connection with the VPN server could not be established.	VPN connection
The content to establish a VPN connection is incorrect. Please try again	VPN connection
Received information to establish VPN connection	VPN connection
VPN connection.	VPN connection
OpenVPN is not installed. Please contact the administrator for more details.	VPN connection
Unable to connect to the VPN possibly due to a problem in the configuration file used.	VPN connection
Could not start the VPN connection.	VPN connection
Unable to connect VPN.	VPN connection
Unable to connect VPN through SAML.	VPN connection
Could not disconnect the user from the server.	VPN connection
Disconnected due to policy or VPN config change.	VPN connection
Lost connection to VPN.	VPN connection
Not connected to VPN.	VPN connection
Automatically connected to the VPN.	VPN connection
There are no VPN configuration files on the current policy, so the VPN window will be disabled. Please contact an administrator for more details.	VPN connection
VPN connection was closed due to VPN configuration file or policy change.	VPN connection
The AutoConnect and OTP options cannot be enabled at the same time.	VPN connection
Not connected to VPN	VPN connection
VPN connection was closed. Open the VPN window to see more details about the disconnection.	VPN connection
It has been detected that you have an active VPN connection, when you exit OpenNAC Agent you will disconnect.	VPN connection
The response from opennac is not valid.	VPN connection
The server response does not contain all the information required for WireGuard.	VPN connection
WireGuard is not installed. Please contact the administrator for more details.	WireGuard

Flow Charts

In this section we will see some of the main flow charts for the different Agent functionalities.

GatherEvents

Connect VPN

Disconnect VPN

Autoconnect VPN