Update service troubleshooting docs

Author: webprofusion-chrisc

docs/backgroundservice.md

@@ -13,22 +13,26 @@ By default the background service runs a local http API server on port 9696 for
 
 ## Custom configuration and Troubleshooting "..service not started" error
 
-The certify background service operates a local API for the app on port `9696` by default. If this port is in use by another application/service (or for some other reason it cannot create a binding to `localhost:9696`, or a security product is preventing **local** port access) then you will see the message 'Service not started'.
+The certify background service operates a local API for the app on port `9696` by default. If this port is in use by another application/service (or for some other reason it cannot create a binding to `127.0.0.2:9696` (localhost), or a security product is preventing **local** port access) then you will see the message 'Service not started'.
+
+- `servers.json` : This is the connection information used by the UI to connect to the background service.
+- `serviceconfig.json` : These are the service settings and includes the host/ip and port the service will listen on, so it needs to match the details in `servers.json`.
 
 :::info
-If you are repeatedly seeing the "Service Not Started" error, first try deleting `serviceconfig.json` and `servers.json` from C:\ProgramData\Certify\ then restart the background service and the app. This can help if automatic port negotiation has gotten out of sync.
+If you are repeatedly seeing the "Service Not Started" error, first try deleting `serviceconfig.json` and `servers.json` from C:\ProgramData\Certify\ then restart the background service and the app and these config files will be recreated. This can help if automatic port negotiation has gotten out of sync.
 
 In some cases antivirus software products (such as *ClamWin*, *Watchguard Advanced EPDR*, *ESET*) have been known to prevent the Certify servicing installing properly or prevent some core features working like our temporary http challenge service listener.
 :::
 
-If the default port 9696 is already in use however you can manually specify the settings required by editing/adding the file `c:\programdata\certify\serviceconfig.json` with content as per the following (adjusted as required) then restarting both the service and UI:
+If the default port 9696 is already in use however you can manually specify the settings required by editing/adding the file `c:\programdata\certify\serviceconfig.json` (and servers.json) with content as per the following (adjusted as required) then restarting both the service and UI:
 
 ```json
 {
   "host": "localhost",
   "port": 9696
 }
 ```
+Any local IP (or `localhost`) can be used, local loopback addresses are strongly recommended so that remote access is not possible.
 
 For example an alternative configuration might be:
 
@@ -56,12 +60,14 @@ To operate properly the background service needs to be able to register an http
 
 ### Allow Local System account to bind an http listener to the service port
 
-In some cases you need to explicitly allow the service to listen as an http service on the localhost IP address. To Do so run the following command from the command line as an Administrator:
+In some cases you need to explicitly allow the service to listen as an http service on the localhost IP address. To do so run the following command from the command line as an Administrator, substituting your choice of listening IP address and port:
 
 `netsh http add urlacl url=http://127.0.0.1:9696/ user="NT AUTHORITY\SYSTEM"`
 
 ### Enable http listener IP address
 
+If your system is restricting which IP addresses can listen for HTTP traffic you may find you need to enable iplisten for the service IP.
+
 As per https://docs.microsoft.com/en-us/windows/win32/http/add-iplisten enable any IPv4 address to listen for http. :
 
 ```bat
@@ -73,10 +79,10 @@ netsh http add iplisten ipaddress=::
 ```
 
 
-Or to target a specific IP address such as 127.0.0.1 (localhost):
+**Or to target a specific IP address such as 127.0.0.2 (our default local loopback IP setting)**:
 
 ```bat
-netsh http add iplisten ipaddress=127.0.0.1
+netsh http add iplisten ipaddress=127.0.0.2
 ```
 You should monitor other effects on other services when changing the IP listen configuration. We have seen one report of Exchange/Outlook slowing down when the 0.0.0.0 address iplisten is enabled.
 

docs/guides/troubleshooting.md

@@ -3,6 +3,9 @@ id: troubleshooting
 title: Troubleshooting
 ---
 
+## If the UI shows a "Service Not Started" message.
+If you see this type of error reported by the UI, see [Background Service](../backgroundservice.md) for more troubleshooting information.
+
 ## Issues communicating with the CA
 In normal use the app must be able to talk to the ACME API for your chosen Certificate Authority (e.g. Let's Encrypt). If you see an error reported such as `The ACME service (directory) is unavailable.` this would indicate your machine is not able to establish communication with the CA service.
 
@@ -22,5 +25,12 @@ If the above test works OK then next thing would be to determine if the CA is re
 
 You can use tools such as Telerik Fiddler to see the https conversation between your machine and the CAs API but you can also try enabling Debug logging in the app. To do so, edit `C:\ProgramData\certify\serviceconfig.json` and set the `"LogLevel"` field to `"debug"` instead of `"information"`, then restart the Certify background service and attempt your request again (just click "Request Certificate" on a managed certificate). The `C:\ProgramData\certify\logs\session*.log` file will then include the actual http conversation between you and the CA and you can use this to see if the CA is returning an error that the app is unable to interpret, or if the connection is simply not operating normally.
 
-# Alternative Solutions
-Occasionally you may be unable or unwilling to resolve the connectivity issue with the CA system. In this case we would suggest the next thing to try is to [use a different CA](certificate-authorities.md). You can try this for a single managed certificate and if that works change your default CA over to the new preferred CA.
+### Alternative Solutions
+Occasionally you may be unable or unwilling to resolve the connectivity issue with the CA system. In this case we would suggest the next thing to try is to [use a different CA](certificate-authorities.md). You can try this for a single managed certificate and if that works change your default CA over to the new preferred CA.
+
+# Domain Validation Issues Causing Failed Renewal
+## HTTP domain validations suddenly failing
+If you find you are unexpectedly getting HTTP domain validation failures (particularly "Secondary validation") the most common cause is a Firewall blocking TCP port 80 (http) or you are blocking a range of IP or Geographic locations. To allow only your CAs HTTP validation requests through we recommend using a Web Application Firewall set to allow all http requests to any path starting with `/.well-known/acme-challenge/`. Alternatively block specific countries instead of blocking all countries, as your CA (the default being Let's Encrypt) may choose to validate from any geographic region.
+
+## DNS domain validations suddenly failing
+DNS providers can and do change their APIs periodically which can impact renewals using DNS validation. For instance, GoDaddy changed their API to only allow API use for customers with more than 10 domains. Other DNS providers have retired their older APIs resulting in renewals that use those failing. We recommend that if a problem develops with DNS validation that you ensure you are using the latest version of the app and if the problem persists contact your DNS provider to ask if their API has recently changed.

package.json

@@ -15,17 +15,17 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.3.2",
-    "@docusaurus/preset-classic": "3.3.2",
-    "@docusaurus/theme-mermaid": "3.3.2",
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/preset-classic": "3.4.0",
+    "@docusaurus/theme-mermaid": "3.4.0",
     "@mdx-js/react": "^3.0.1",
     "prism-react-renderer": "2.3.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.3.2",
-    "@docusaurus/tsconfig": "3.3.2",
+    "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/tsconfig": "3.4.0",
     "@types/react": "18.2.48",
     "typescript": "5.2.2"
   },