QNAP Monitoring in VCF Operations: Setup and Troubleshooting

I built a custom QNAP management pack for VCF Operations 9.1 that connects directly to the NAS over HTTPS. This post covers storage visibility, deployment and the authSid authentication issue I encountered, including password encoding and the difference between Builder and integration-account credentials.

The pack is installed, the full Builder collection test passed, and scheduled persistence has now been observed. This update adds the QNAP dashboard and alerts configured in the lab, plus the results and limits of independent QTS resilience tests.

The design uses the built-in Management Pack Builder and QTS CGI endpoints. The current release was upgraded in place, retained the existing account and volume identity, and requires no bridge appliance.

The environment

The integration was tested with:

• QNAP TS-435XeU
• QTS 5.2.9.3451
• VCF Operations 9.1.0.0400.25541561
• The built-in VCF Operations Management Pack Builder

This management pack was tested on a QNAP TS-435XeU running QTS 5.2.9.3451. It is expected to work with other QNAP systems running the same QTS release, provided they expose the same CGI endpoints and response structures, but compatibility is not guaranteed. Administrators should validate authentication, discovered objects, metrics, relationships, and permissions before production use. This is a community integration, not a claim of QNAP or Broadcom certification.

How the management pack connects

VCF Operations collector → HTTPS → QNAP QTS

The collector authenticates to QTS, obtains a session token, requests monitoring data, and releases the session.

The installed release collects array, disk, volume, iSCSI service, target, and LUN information. No bridge appliance is used or required.

Finding endpoints that actually worked

One important lesson was to test against the firmware on the NAS instead of assuming that an API example found elsewhere would apply.

The newer REST-style storage and iSCSI paths I tried returned 404 on this QTS installation. The working requests used QTS CGI endpoints instead.

The direct design uses these requests:

Authenticated requests also include the session token in a sid query parameter. Treat those query strings as sensitive when collecting logs or taking screenshots.

These endpoints worked in this environment. Their response structures still need to be revalidated after firmware changes and on other NAS models.

Account permissions matter

The management pack uses a dedicated QTS account to authenticate to the NAS over HTTPS.

In my tests, System Monitoring permission provided access to the system, disk, and volume requests. The iSCSI request needed System Management permission as well.

That distinction is important. System Management is a broad role with management capabilities. Giving an account read-only shared-folder permissions does not make its system-management access read-only.

The pack itself makes monitoring requests plus login and logout requests, but the account has more authority than those requests require. Review that tradeoff before using this design. A reduced pack without the iSCSI request would need separate validation if the broader role is unacceptable.

Use the NAS HTTPS port—not just the browser port

My normal QTS browser session used HTTP on port 8080. The successful direct collector connection used HTTPS on port 443.

Those are different services. The port you happen to use to open the QTS desktop is not necessarily the port to enter in an HTTPS integration.

Use the HTTPS management port actually configured on your NAS. The collector also needs network access to that port; being able to open QTS from an administrator workstation does not prove that the VCF collector can reach it.

For production, use certificate validation with a trusted certificate whose subject alternative name matches the hostname or IP address used by the collector. My lab certificate was self-signed and lacked the required SAN, so testing used No Verify. That encrypts the connection but does not authenticate the server’s identity. It is a lab limitation, not the recommended production configuration.

The authentication detail that caused the most confusion

The preview’s login request is a form-encoded POST. Its body uses two credential references:

user=${authentication.credentials.username}&pwd=${authentication.credentials.encoded_password}

The request’s Content-Type is:

application/x-www-form-urlencoded

For this design, the username must be URL-encoded. An ordinary alphanumeric username does not change when encoded.

The password requires two transformations, in this order:

1. Base64-encode the password’s UTF-8 bytes.
2. URL-encode the resulting Base64 string.
3. Enter that result in the Encoded Password field.

Do not enter the plain password, add a newline, or encode the final value a second time. Base64 characters such as +, /, and = need the URL-encoding step because the value is being placed into a form body.

Base64 is not encryption. The encoded value is a password-equivalent secret. Generate it with an approved local tool, not an online encoding website.

In the updated pack, Username is non-sensitive so it is easier to inspect. Encoded Password remains sensitive.

Why Builder validation passed but adding an account failed

After the pack was built and installed, I encountered this error while validating the integration account:

Could not retrieve response body field authsid from
auth json object at path [authSid]

The key lesson: Builder test credentials and integration-account credentials are separate.

The credentials supplied while building the pack let Builder test a representative environment. Installing the pack does not copy those credentials into the account used for ongoing collection.

The integration account still needs its own NAS address, HTTPS port, collector selection, username, and correctly encoded password. Once I entered the encoded password in that account, its connection validation worked.

During troubleshooting in Builder, the collector also received HTTP 200 responses with Content-Length: 0 from the login endpoint. The request appeared successful at the HTTP level, but there was no response body and no session token to extract. Re-entering the saved credentials with the correct encoding restored a valid authentication response.

That does not mean every authSid error is a password problem. It means the error describes a missing expected field, not the underlying cause. Check the actual login response before changing the mapping or granting more permissions.

What the installed release collects

The current design defines six custom object types:

• Array: identity, firmware, memory, temperatures, fan readings, and numeric CPU usage.
• Disk: identity, health/status, capacity, temperature, and available SMART properties.
• Volume Usage: total and free capacity in bytes while preserving the existing installed Volume ID binding.
• iSCSI Service: service settings and aggregate target, LUN, and initiator counts.
• iSCSI Target: stable identity, status, and mapped-LUN count.
• iSCSI LUN: stable identity, status, mapping, thin-provisioning state, sector size, and exact capacity in bytes.

The final live Builder collection completed in two seconds:

The tested inventory included one array, six disks, one real volume, one iSCSI service, two targets, and two LUNs. Management Pack Builder reported the installed integration as version 1.0.0.7. The existing account was retained and reported Collecting.

Latest validation and Operations content

QNAP Storage Operations dashboard

The lab now has a QNAP-scoped inventory and collection-status view plus QNAP alert history. The inventory shows object type, policy, collection state, and data-receiving state, so collection problems can be distinguished from disk or LUN health conditions.

• QNAP Disk Temperature Is High: Temperature C > 55, Warning, with QTS airflow, fan, ambient-temperature, and SMART-health guidance.
• QNAP iSCSI LUN Is Not Ready: LUN Status Code != 0, Critical, with target mapping, backing-volume, maintenance-mode, and recovery guidance.

Both alert definitions were configured in the default policy. Their recommendations explain recovery checks and maintenance mode for intentional service work.

Independent resilience checks

Short-lived test sessions confirmed that explicit logout invalidated a QTS session and a fresh login recovered health access. An intentional HTTP 404 did not invalidate the same session’s valid health request. An intentionally wrong password was rejected, followed by successful authentication with the current password. Test-client certificate checks rejected the lab certificate under default trust and with local certificate trust but a mismatched endpoint name. Test sessions logged out cleanly; the production adapter session was not touched.

Evidence limit: these are source-level checks, not end-to-end VCF adapter fault injection. They do not prove automatic adapter retry during a mid-cycle failure, actual NAS password rotation, or missing-metric propagation in Operations. A healthy running adapter is not evidence of those failure paths.

Compatibility and scope boundaries

The current implementation scope is closed on the project roadmap. The tested platform remains TS-435XeU with QTS 5.2.9.3451 and VCF Operations 9.1.0.0400.25541561; this is not a universal QTS compatibility or storage-performance claim.

• Other models, QTS releases, multiple real data volumes, and multi-physical-CPU systems require end-user validation.
• The tested full design requires System Monitoring plus broad System Management authority for iSCSI.
• Pool/RAID endpoint candidates returned HTTP 404 on the tested QTS release. RAID groups, pools, IOPS, throughput, latency, initiator objects, and custom events are not modeled.
• Fan mappings cover the tested hardware.

Check the available objects, metrics, permissions, and validation scope against your requirements before adoption.

Deployment at a glance

1. Prepare a dedicated QTS account and review the required role permissions.
2. Confirm collector-to-NAS HTTPS connectivity and certificate configuration.
3. Import the design JSON into Management Pack Builder.
4. Supply representative-environment credentials using the required encoding.
5. Test session creation, session release, and the health request.
6. Run a full collection and inspect the returned objects and values.
7. Install the validated pack through Builder.
8. Add an integration account with its own correctly encoded credentials.
9. Validate the account, then verify scheduled collection and recent data timestamps.

The reusable artifact produced in this project is a Builder design JSON. Its ZIP is a distribution archive, not an installable .pak. Installation and the in-place upgrade were performed through the built-in Builder.

Final thoughts

The QNAP management pack brings storage visibility into VCF Operations through direct HTTPS collection. The key setup requirements are endpoints supported by the QTS version, appropriate account permissions, and correctly encoded credentials.

The most useful troubleshooting takeaway was also the simplest: a successful HTTP request is not necessarily a successful login, and a successful Builder test is not the same as a configured integration account.

Start with a valid session, verify the data you actually receive, and expand the monitoring coverage from there.