6.1.14. Agent Troubleshooting

In this section, you can find information about some of the most common errors related to the Agent, as well as the locations of various configuration files, logs, and other relevant resources in different operating systems.

6.1.14.1. Agent installation error on MacOS

If you encounter any error during the Agent installation process on MacOS, execute the following steps:

  1. Open the terminal.

  2. Execute the following command:

xcode-select --install

  1. Execute the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  1. Retry the Agent installation.

These steps should help resolve any issues encountered during the installation process.

6.1.14.2. Install/Update logs

When installing or updating the Agent, you can examine specific log files prefixed with OCF_ to gain insight into these processes.

Windows installation logs

C:\Users\{USER}\AppData\Local\Temp

Windows update logs

C:\Windows\Temp

6.1.14.3. 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.linux/config/appsettings.json

6.1.14.4. 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

6.1.14.5. 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.

6.1.14.5.1. Wireguard

  • Windows

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

  • Mac

/Library/com.opencloudfactory.opennacagent/wireguard

  • Linux

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

6.1.14.5.2. OpenVPN

  • Windows

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

  • Mac

/Library/com.opencloudfactory.opennacagent/openvpn

  • Linux

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

6.1.14.6. 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

6.1.14.7. 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\{USER}\AppData\Local\OpenCloudFactory\OpenNAC Agent\OpenNAC UI Console\LogsOpenCloudFactory.Agent.UI.log

  • Mac

/Users/{USER}/.local/share/OpenCloudFactory/OpenNAC\ Agent/OpenNAC\ UI\ Console/Logs/OpenCloudFactory.Agent.UI.log

  • Linux

/home/{USER}/.local/share/OpenCloudFactory/OpenNAC\ Agent/OpenNAC\ UI\ Console/Logs/OpenCloudFactory.Agent.UI.log

6.1.14.8. 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.

  1. 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}"

  1. 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.

  1. 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"

  1. 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"

  1. 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.

  1. 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.

  1. 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}"

  1. 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.

6.1.14.9. Log format

Logs can be of type TRACE, DEBUG, INFO, WARN,*ERROR*, FATAL, or OFF. If the DEBUG log level option is specified in Agent profile, the Agent will print debug lines in the 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 the Debug mode will record more information in the logs stored by the Agent application.

To activate the Debug mode option in the NextGen Portal:

  1. Go to the Administration Portal and navigate the Configure > Agent > Profiles section.

  2. Click on the edit icon located at the right-end of the profile row.

  3. Click on edit located at the right- end of the General row.

  4. Select the DEBUG log level option:

../../_images/debugmode_ng.png


  1. click on Confirm to save the changes.

To activate the Debug mode option in the Default Portal:

  1. Go to the Administration Portal and navigate to the ON Agent > Agent Profiles section.

  2. Select the Agent profile and click on Edit.

  3. Scroll down to the Service configuration section and select the DEBUG log level option:

../../_images/debugmode1.png


  1. Scroll down to the Taskbar configuration section and select the DEBUG log level option:

../../_images/debugmode2.png


For further information, see the Agent > Profiles section.

6.1.14.10. 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

The user specified does not have 2FA configured.

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

The VPN 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

Could not disconnect from the network.

Servers

The response from server is not valid.

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.

SAML workflow

Process canceled due to window closing.

SAML workflow

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

Server response does no contain all the information required for WireGuard

WireGuard

The license has expired. Please contact an administrator.

Licensing

No license detected. Please contact an administrator.

Licensing

Something went wrong.

Generic error

The Agent will also send Policy notifications in the following cases, as long as a new payload response has been received:

  • After every full payload

  • After every scan payload

  • After every manual payload

  • After a policy change

  • After the message content has been changed

6.1.14.11. Flow Charts

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

6.1.14.11.1. GatherEvents

../../_images/gatherProcess.png


6.1.14.11.2. Connect VPN

../../_images/connectVPN.png


6.1.14.11.3. Disconnect VPN

../../_images/disconnectVPN.png


6.1.14.11.4. Autoconnect VPN

../../_images/autoconnect.png