From 451fc36518a17d0414f572a6dc9396ddfdaf3ee1 Mon Sep 17 00:00:00 2001
From: "Greg T. Wallace" <greg@gregtwallace.com>
Date: Mon, 23 Jun 2025 19:55:15 -0400
Subject: [PATCH] readme: update compatibility and troubleshooting

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index d673c1f..9286344 100644
--- a/README.md
+++ b/README.md
@@ -53,13 +53,14 @@ This project aims to solve all of these problems by accepting the most
 common key and cert file format (PEM) and by being 100% open source
 and licensed under the GPL-3.0 license.
 
-## Compatibility Notice
-
-Both NMC2 and NMC3 devices should be fully supported. However, I have one
-NMC2 device in a home lab and have no way to guarantee success in all cases.
-
 ### Key Types and Sizes
 
+Ensure you select an appropriate key!
+
+NMC2 is extremely picky about the key type and size it supports. NMC3 is a bit
+more flexible. Beware, some ACME clients will generate an ECDSA key by default
+which is NOT supported by NMC2.
+
 NMC2:
 - RSA 1,024, 2,048, 3,072* bit lengths.
 
@@ -80,22 +81,60 @@ NMC3*:
 this size if possible. Most (all?) public ACME services won't accept keys 
 of this size anyway.
 
-### General Troubleshooting
+### Compatibility Notice
+
+Both NMC2 and NMC3 devices should be fully supported. However, I have one
+NMC2 device in a home lab and have no way to guarantee success in all cases.
 
 My setup (and therefore the testing setup) is:
 - APC Smart-UPS 1500VA RM 2U SUA1500RM2U (Firmware Revision 667.18.D)
 - AP9631 NMC2 Hardware Revision 05 running AOS v7.1.2 and Boot Monitor 
   v1.0.9.
 
-If you have trouble, your first step should be to update your NMC's firmware.
-Many issues with this tool will be resolved simply by updating to the newest
-firmware.
+Generally, if there is a compatibility issue, there is a good chance you will
+not see an error. Rather, the NMC will silently fail and you'll only know 
+something went wrong because the NMC's certificate didn't update, or it regenerated
+a self-signed certificate that you'll see upon your next connection attempt. 
+I've tried to add some `WARNING` messages to the tool to indicate what might
+be going wrong, but the list is definitely not exhaustive.
 
-If you have a problem after that, please post the log in an issue and I can 
-try to fix it but it may be difficult without your particular hardware to 
-test with.
+### Troubleshooting
 
-In particular, if you are experiencing `ssh: handshake failed:` first try
+Suggested troubleshooting steps:
+- Review the `Key Types and Sizes` and `Compatibility Notice` sections of this
+  README.
+- Update your NMC's firmware to the latest version.
+- Read this tool's output, look specifically for any `WARNING` messages and
+  adjust your certificate accordingly.
+- Test using an RSA 2048 bit key to obtain a certificate from Let's Encrypt.
+  Their certificates are known to work with NMC.
+- Use the official NMC Security Wizard to verify you can create a working
+  certificate and load it into your NMC. If the official tool does not work
+  switching to this tool won't help.
+
+If you have tried all of these steps and are still experiencing a problem,
+you may open an Issue on GitHub. 
+
+Include:
+- The full command you are running that is causing the problem. 
+- The full log of this tool's output when you run the command. Append the
+  `--debug` flag to your command to get the debug output.
+
+Keep in mind, I am one person with one specific hardware setup. I may not
+be able to help you.
+
+#### NMC3 Install `ssh: parse error in message type 53` Error
+
+Configuring a `System Message` on an NMC3 breaks the install function. I do
+not have an NMC3 and after doing some code review it is highly unlikely I'll
+be able to fix this. Don't use a `System Message` if the install feature is
+important to you.
+
+see: https://github.com/gregtwallace/apc-p15-tool/issues/14
+
+#### Install `ssh: handshake failed` Error
+
+If you are experiencing `ssh: handshake failed:` first try
 using the `--insecurecipher` flag. If this works, you should upgrade your
 NMC to a newer firmware which includes secure ciphers. You should NOT automate
 your environment using this flag as SSH over these ciphers is broken and