POWERSHIELD TROUBLESHOOTING GUIDE

1. When should I enable the secure connection?
2. What are the SMTP settings with gmail?
3. Is Poweshield compatible with Hyper-V management?
3.1 How to configure Powershield to manage Hyper-V?
3.2 UpsConfigHyper-V configuration
3.3 Retireving the virutal machines inside each host
3.4 Retireving the virutal machines inside each host
3.5 Test Hyper-V shutdown
3.6 Hyper-V shutdown
4. How to setup a USB connection over MAC?
5. How to run upsagent in debug?
6. How to run upssetup in debug?

1. When should I enable the secure connection?

The secure connection field is disabled by default. This function should only be used when using a NetMan certified for cybersecurity. It must not be used in any other cases.

2. What are the SMTP settings with gmail?

To configure Gmail as the mail provider, it is essential to follow specific steps. Firstly, ensure that two-factor authentication (2FA) is enabled on the Gmail account.

Image Description: Shows the Gmail interface with inbox and account settings, highlighting user 'Emanuel Guarise', storage usage, and options to manage the Google Account, privacy, and security. It also displays privacy suggestions and security tips.

The process involves navigating to Google Account settings, specifically the "Security" section, to enable "2-Step Verification." This typically requires entering a phone number for verification codes.

Image Description: Details Google Account security settings, showing "2-Step Verification" is off and prompting to add a phone number or other verification methods like passkeys or security keys.

After enabling 2-Step Verification, an "app password" needs to be generated for applications that do not support modern security standards, such as Powershield. This is done within the Google Account's security settings under "App passwords."

Image Description: Illustrates the "App passwords" section for generating a 16-character password for applications like Powershield. The generated password is shown as an example.

Important Note: The app password generated by Gmail may include spaces. When entering this password into the Powershield, ensure all spaces are removed for proper functionality. Subsequently, use this generated app password in the Gmail account settings within Powershield to enable the successful sending of emails.

3. Is Poweshield compatible with Hyper-V management?

Powershield³ can manage Hyper-V, allowing for the shutdown of virtual machines and hosts. An example configuration of UpsConfigHyper-V is described below.

3.1 How to configure Powershield to manage Hyper-V?

This section illustrates the structure of a Hyper-V environment with two or more hosts, based on the Hyper-V Manager running on Windows Server 2022 EN1.

Image Description: Displays the Hyper-V Manager interface listing hosts 'WIN-2022EN1' and 'WIN-2022EN2', with tools for managing virtual machines. It explains that a virtualization server hosts virtual machines and Hyper-V Manager is used for their management.

Powershield³ is installed on Windows Server 2022 EN1 (WIN-2022EN1), identified as the local host for Powershield³. The objectives are to shut down virtual machines on WIN-2022EN2 and then the host itself, followed by shutting down virtual machines on WIN-2022EN1 and then the WIN-2022EN1 host.

3.2 UpsConfigHyper-V configuration

First, configure the Hyper-V host information. The host where Powershield³ is running (local host) should be added first, with the "Local host" slider enabled.

Image Description: Shows the "Config Hyper-V VM management" window for adding Hyper-V hosts, including fields for host details (name/IP, domain, username, password) and a "Local host" toggle. A note emphasizes the need for administrator privileges.

Note: The username must be a local administrator account. If it's not, it must be added to the "Hyper-V Administrator" group.

To add other hosts, press the "+" button. In the example, WIN-2022EN2 is added as a non-local host, so its "Local host" slider is not enabled.

Image Description: The "Config Hyper-V VM management" window is shown again, with WIN-2022EN2 added to the host list. The "Local host" slider for WIN-2022EN2 is disabled. The administrator privilege note is repeated.

Repeat the action to add all desired hosts for management and shutdown.

3.3 Retireving the virutal machines inside each host

To retrieve the virtual machines running on a host, select the host and click the "Retrieve VM from host" button.

Image Description: The "Config Hyper-V VM management" window shows WIN-2022EN1 selected, listing three VMs ("Windows10", "Debian 10", "Windows10-2") with their states (Running/Off) and delay settings. A second view shows WIN-2022EN2 with two VMs ("Debian10-2", "Windows10-3"). The note "Note: not all the virtual machines are running. Some of the virtual machines are off." is displayed.

3.4 Retireving the virutal machines inside each host

If virtual machines cannot be retrieved from a host, running UpsConfigHyperV in debug mode might help identify the cause. Open a command prompt, navigate to the directory where UpsConfigHyper-V is running, and execute the command: UpsConfigHyperV -d.

Image Description: A command prompt window shows the execution of "UpsConfigHyperV -d" with debug output. Another image displays the "Config Hyper-V VM management" window alongside detailed log entries for host and VM status, including VM states like "Off."

The output provides debug information. The process involves selecting "Configuring Hyper-V VM Shutdown," choosing the host, and then selecting "Retrieve VM from host." The log file "debugs.log" will contain details about why VMs cannot be retrieved. Send "debugs.log" to the service department for assistance. This procedure can be repeated for all hosts.

3.5 Test Hyper-V shutdown

After completing the configuration, it is recommended to perform a test. Enable the "Test Hyper-V shutdown" slider and save the settings.

Image Description: The "Config Hyper-V VM management" window shows the "Test Hyper-V shutdown" slider enabled. It lists hosts and VMs. Instructions mention running ups_shut.bat from C:\ProgramData\Upsmon and checking the resulting ups.log file. The log excerpt shows test execution details.

The provided log excerpt shows the start of the test, host information (WIN-2022EN1, WIN-2022EN2), OS details, and simulated shutdown actions for VMs and hosts. It notes that only running VMs at the time of shutdown are logged.

3.6 Hyper-V shutdown

To perform a real shutdown, the "Test Hyper-V shutdown" option must be disabled.

Image Description: The "Config Hyper-V VM management" window shows the "Test Hyper-V shutdown" slider disabled. It also shows the "POWERSHIELD3 Configuration" window with settings for device identification and system shutdown actions, including enabling device shutdown.

When the mains power is removed from the UPS, the shutdown process will commence for all virtual machines and hosts. The host running Powershield³ (local host) will be shut down last. To enable the shutdown of the local host, ensure the shutdown is enabled in the "Upssetup" configuration.

The log file ups.log will contain the record of the real shutdown process.

4. How to setup a USB connection over MAC?

Follow these steps to set up a USB connection on macOS:

Stop the Powershield/Upsmon service from the command line by typing: sudo launchctl stop com.rps.upsmon and pressing Enter.
Note: It is recommended to use a user with root permissions.
Verify that the application is allowed to load by following the steps in the screenshots below. The application must be permitted to load.
Image Description: macOS "About This Mac" window, navigating to "System Preferences."

Image Description: macOS "System Preferences" window, showing navigation to "Security & Privacy."

Image Description: macOS "Security & Privacy" pane, allowing downloaded applications, with a note about system software being blocked and an "Allow" button.
Navigate to /Library/Extensions in the command line and press Enter.
Type ls and press Enter to check for "USBUPSDriver" items. If found, execute the command sudo kextload for each item:
- If USBUPSDriver is present, type sudo kextload USBUPSDriver.kext and press Enter.
- If USBUPSDriver2 is also present, type sudo kextload USBUPSDriver2.kext and press Enter.
- If USBUPSDriver3 is also present, type sudo kextload USBUPSDriver3.kext and press Enter.
Note: If the kextload command is not allowed, use sudo kextutil instead for each USBUPSDriver.
Repeat step 2.
If the USB cable is connected, disconnect and reconnect it.
Restart the Powershield/Upsmon service from the command line by typing: sudo launchctl start com.rps.upsmon and pressing Enter.

5. How to run upsagent in debug?

If a communication issue occurs, you can run UpsAgent in debug mode to generate a debug file for analysis by the service department.

Open a command prompt.
Navigate to the C:\Program Files\Upsmon directory or C:\Program Files\Powershield3.
Run the command: upsag_nt -debug.
Image Description: A command prompt shows execution of "upsag_nt -debug" with hexadecimal data representing communication packets.
Stop the debug process after 20 or 30 seconds by pressing Ctrl+C.
Open the C:\ProgramData\Upsmon directory.
Locate the file debug.log and send it to your service contact.

6. How to run upssetup in debug?

If a mail issue occurs, you can run UpsSetup in debug mode to generate a debug file for analysis by the service department.

Open a command prompt.
Navigate to the C:\Program Files\Upsmon directory or C:\Program Files\Powershield3.
Run the command: upssetup -debug.
Image Description: Command prompt showing "upssetup -debug" execution. The "UPSMON Configuration" window is also displayed, showing modules like "Mail and messages."

A test mail window shows WINSOCK.DLL information and SMTP connection status.
Open "Mail and messages" and perform a test mail command. The following window will appear:
Image Description: A test mail window showing WINSOCK.DLL information and SMTP connection status.
Leave the test mail window running until completion.
Exit the UpsSetup window.
Open the C:\ProgramData\Upsmon directory.
Locate the file debugmail.log and send it to your service contact.

Changelog

DocRev	Date	Change
rev00	28/03/2025	First release