Installation
In general, the installation of the Ziti Desktop Edge for Windows goes smoothly. Currently, the only known time when the installation will fail is when the service that provides the actual connectivity to a Ziti Network fails to start. Troubleshooting this is as easy as going into the log folder and looking at the ziti-tunnel.log. This log should indicate what the actual issue is.
This log file is at C:\Windows\System32\config\systemprofile\AppData\Roaming\NetFoundry
These are the two types of failure seen when installing the service:
-
A bad download. At least one instance of a 'bad download' has affected the installation process. This was solved by re-downloading the install package and re-running it.
Installing an Identity
Once the Microsoft Windows Desktop Edge is installed, the user will need to "Add an Identity" provided by the NetFoundry platform by downloading the provided .jwt file. If during this step the user receives the error "Code 2:Object reference not set to an instance of an object" as shown.
Please have the user do the following steps:
Open System from Windows search box -> Click on the Advanced System Settings -> Click on Advanced tab under System properties -> Click on Environment Variables -> Select Path under System Variables -> Click on Edit and add the powershell path C:\Windows\System32\WindowsPowerShell\v1.0\ -> select the power shell entry and keep clicking on move up button until you have this path as the first entry in path.
Add the identity again.
Service Startup
If the service fails during startup the Ziti Network will not be available and the UI will display a message indicating: "Service Not Started". To diagnose this issue, you must review two logs: ziti-tunnel.log and cziti.log. These logs will contain the reason the service did not start properly.
Both these files are at C:\Windows\System32\config\systemprofile\AppData\Roaming\NetFoundry
If the log files are not present or your installation failed with an error and during the installation and you see the "Error 1067: The process terminated unexpectedly"
The Windows machine has a PATH variable that does not include numerous important paths. The below needs to be added:
* %WINDIR%
* %WINDIR%\System32
* %WINDIR%\system32\WindowsPowerShell\v1.0
Add the above & Ziti Desktop Edge Service should successfully start.
Usage
During usage if a service is not accessible it's most often (but not always) because of network configuration as opposed to a bug in the client. Here's a list of actions to perform to to troubleshoot a client that doesn't seem to be working.
Basic Troubleshooting
Step 1: Verify you're running the latest version of the Ziti Desktop for Windows. Click on Main Menu and look to see if there is an update available. If there is go to https://github.com/openziti/desktop-edge-win/releases and download the latest version.
Step 2: Open the Ziti Desktop Edge for Windows UI and make sure an identity shows up.
Step 3: Looking at the identity and make sure the services count is greater than 0. If no services show up the overlay network configuration is incorrect and needs correction. This is done in the NetFoundry Platform by your Network Administrators.
Step 4: Looking at the identity make sure the name of the identity is the one expected to see.
Step 5: Looking at the identity - verify the toggle is ‘on’
Step 6: Click on the identity - the identity details card will pop up. Look at the services listed and make sure the service you expect to see is listed
Step 7: Verify the service does not have a warning sign displayed. A warning sign will generally mean the network configuration is incorrect and more than one service will have the same intercept hostname and port specified. Notify your network administrator about the conflicting services, and ask them to update one or both services accordingly.
.
If above items do not solve the issues one can take a look at the various logs that are generated for other things that might be causing issues with your services. Increase logging and recreate the problem to aid debugging. Up the logging to at least debug sometimes trace or verbose will be asked for. DO NOT LEAVE LOGGING ON TRACE or VERBOSE. These logging levels are very disk intensive and should only be used for short periods of time.
-
With logging on debug, make sure you see DNS requests matching the service you expect. In ziti-tunneler.log you should see log messages indicating the service name and the intercept/port like:
- Verify DNS requests are successfully processed by looking at ziti-tunnel.log for messages like:
- Verify you see these sorts of messages in cziti.log:
- If all these checks pass - collect all the logs open a ticket with NetFoundry Support attaching all logs to the ticket.
DNS Issues
NetFoundry intercepts traffic for particular applications via the services that make up the AppWANs that have been enabled for you by the Administrators. If you experience an issue with DNS resolution for those Services or for other general websites or applications you are trying to use please turn the Desktop Edge OFF and then Back ON to allow the DNS to be reset.
Advanced Troubleshooting
1. Failed to enroll
While your JWT token is still valid and you get a "failed to enroll" message in WDE, check the application logs. If you see the following error, it means that the endpoint is not able to connect to the controller. A VPN or proxy etc is interfering in-between.
ZitiDesktopEdge.ServiceClient.DataClient failed to enroll. failed to parse JWT: %s could not retrieve token URL certificate: could not contact remote server [https:.................................production.netfoundry.io:443]
Please check what's interfering with the reachability of the endpoint to the controller. The endpoint should be able to reach the controller URL.
You will not be able to enroll to the network with the identity if you use an expired identity file. Make sure from the console that the token hasn't expired. If you use AD sync for endpoint lifecycle management, NetFoundry will automatically re-issue token for expired keys for "unregistered" endpoints
The expiration date for an identity is available when creating, and by selecting Edit from the ellipsis menu at the right of the endpoint in the console, prior to registration, just below the QR code.
2. The most difficult error to troubleshoot is when the policies in place do not allow for the client to connect to any edge routers. Currently this error will only be seen in the cziti.log file. This line will be shown:This situation is entirely an overlay configuration issue. This configuration is done by the Network Administrators. They will need to grant the identity access to one or more Edge Routers. In the NetFoundry Platform go to “Manage Edge Routers” → “Manage Edge Router Policies” and make sure the policies in place grant endpoints access to one or more router that is ‘public’ (can accept edge connections)
- Look through the logs (ziti-tunneler.log and cziti.log) to see if there are any ERROR or WARNING messages that stand out - file an issue accordingly with NetFoundry Support and attach all logs.
- Network administrators should
- Verify the type of termination of the service in question. Is it router-terminated or hosted by an identity?
- Is the router/identity online?
- Can the router/identity dial the service? If not you will see an error such as: lib/ziti_tunnel_cbs.c:25 on_ziti_connect(): ziti dial failed: Connection closed. You’ll need to gain access to the ‘terminating’ endpoint and probe the destination Host/IP and port.
2. Unable to uninstall/update WDE:
Problem:
User tries to uninstall WDE from the windows device as an Administrator while the installation was done on the same device as a different windows user ( not as admin) . This throws the following error:
Reason:
When the user tries to install ziti desktop edge, it copies the msi file into the user's appdata folder of the logged-in user. Install happens from that file location. If the user wants to uninstall the software, he / she has to login using the same windows user login id otherwise, windows will not be able to find the msi file to uninstall the software.
3. Troubleshooting NetFoundry exe blocked by Antivirus and NetFoundry traffic blocked by web security or proxy
1. The web security solution should bypass all Netfoundry IPs / URLs and the destinations that are connected via NetFoundry. The details can be found here: https://support.netfoundry.io/hc/en-us/articles/4402361752717-Firewall-Requirements
2. The NetFoundry EXEs should be allowed/whitelisted in the antivirus solution.
Log Files
The logs can all be collected using the UI by going to Main Menu -> Feedback. You'll get the latest logs attached to an email ready to be sent off for support.
Sometimes more logs might be required. These logs can be collected by running the collect-logs.ps1 script located in the installation folder of the Ziti Desktop Edge for Windows.
The log files from the service require administrator privilege to access and are located at: %windir%\system32\config\systemprofile\AppData\Roaming\NetFoundry