python-netgear-switch-library 0.0.post360__tar.gz → 0.0.post404__tar.gz

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-netgear-switch-library
-Version: 0.0.post360
+Version: 0.0.post404
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License-Expression: Apache-2.0

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/api/protocols.rst

@@ -51,6 +51,8 @@ HTTP web UI
 
 .. automodule:: netgear_switch.protocols.http.forms
 
+.. automodule:: netgear_switch.protocols.http.goahead
+
 .. automodule:: netgear_switch.protocols.http.crypt
 
 .. automodule:: netgear_switch.protocols.http.session

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/fake/index.rst

@@ -60,8 +60,8 @@ with a comment naming the host and firmware version it was observed on. A
 finding that lives only in a report gets regressed by the next change.
 
 Tools that know nothing about this library have cross-checked it too. The
-third-party ProSafeLinux NSDP implementation decodes both mock switches
-completely, every value matching the seed; the C tool ``ngadmin`` validated the
+third-party ProSafeLinux NSDP implementation decodes the GS110EMX and GS105PE
+mocks completely, every value matching the seed; the C tool ``ngadmin`` validated the
 packet header — and surfaced a real four-byte sequence-number bug in the
 process, since fixed. A mock validated only by the client that talks to it
 proves nothing.

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/fake/internals.rst

@@ -140,8 +140,10 @@ A mock validated only by the client that talks to it proves nothing, so the NSDP
 face has been driven by third-party implementations that know nothing about this
 library:
 
-* **ProSafeLinux** decodes both mock switches completely, and every value it
-  reports matches the seed.
+* **ProSafeLinux** decodes the GS110EMX and GS105PE mocks completely, and every
+  value it reports matches the seed. Those two, not all three NSDP models: the
+  GS305EP seed is hand-invented, so decoding it would only confirm this
+  library's own invention.
 * **ngadmin** (a C implementation) validated the packet header — and surfaced a
   real four-byte sequence-number bug in the process, which was fixed.
 

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/fake/testing.rst

@@ -130,10 +130,11 @@ Every backend takes an injected client:
        transports block, so :py:class:`~netgear_switch.aio_api.AsyncSwitch` has no CLI
        backend and takes no ``cli_client``.
 
-All four at once
-----------------
+All three at once
+-----------------
 
-One mock, one facade, three protocols — what makes cross-backend behaviour
+One mock, one facade, three protocols — SNMP, the web UI and the FASTPATH CLI
+answering the same question. This is what makes cross-backend behaviour
 testable without hardware:
 
 .. tab-set::

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/guide/concepts.rst

@@ -57,10 +57,17 @@ A backend is *the protocol an operation travels over*:
        transports; ``CONSOLE`` is a serial line rather than a network backend,
        so it is never registered on a model.
 
-Every read and every write is implemented on every backend a model has. That is
-deliberate: if SNMP writes are locked down on your network, or the web UI is the
-only port through a firewall, you can pick a different protocol and get the same
-answer. :doc:`../models/support` lists the gaps that remain.
+Backend parity is the design aim: an operation should work on every backend a
+model has, so that if SNMP writes are locked down on your network, or the web UI
+is the only port through a firewall, you can pick a different protocol and get
+the same answer.
+
+Where that does not hold, the reason is recorded rather than glossed over. Some
+are limits proven against the hardware — the GS728TPP's SNMP agent refuses every
+documented way of creating a VLAN, while its own web UI creates one without
+complaint — and others are pages or commands nobody has built yet.
+:doc:`../models/support` marks each one. Either way the library refuses by name;
+it never substitutes a protocol you did not ask for.
 
 Dispatch: exactly one backend, every time
 -----------------------------------------

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/guide/quickstart.rst

@@ -185,9 +185,13 @@ back to another protocol — see :doc:`concepts`.
          # has no SSH/telnet/console backend. Use SyncSwitch, or:
          #   await asyncio.to_thread(sync_switch.get_vlans, backend=Backend.SSH)
 
-That the three agree is asserted, not assumed —
-``tests/test_cross_backend_equivalence.py`` compares them for every model with
-more than one backend. They agree on the *physical* ports; SNMP also reports
+That they agree is asserted, not assumed, and by two suites rather than one:
+``tests/test_cross_backend_equivalence.py`` compares HTTP against NSDP or SNMP,
+while ``tests/virtual/test_cli_cross_backend.py`` and
+``tests/virtual/test_cli_gsm7228ps_parity.py`` bring the FASTPATH CLI into the
+same comparison — the CLI is deliberately absent from the first file, so citing
+it alone would overstate what is checked. They agree on the *physical* ports;
+SNMP also reports
 internal and link-aggregation interfaces that a web UI's port table does not
 list, and one model has a VLAN where SNMP shows configured members and the
 web UI shows current ones. Both are real properties of the interfaces, and the

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/guide/reading.rst

@@ -19,7 +19,11 @@ The operations
      - ``list[PortStatus]``
      - Port number, ``ifName``, admin state, link state, speed in Mbit/s, and
        the operator-set description (``ifAlias``) where the backend can read
-       one.
+       one. ``speed_config`` carries the port's **configured** speed/duplex,
+       which is a different question from the negotiated ``speed_mbps`` —
+       see :ref:`speed-vs-negotiated`. The CLI and the GoAhead web UI both
+       report it; SNMP and NSDP leave it ``None``, because ``ifSpeed`` and
+       NSDP's port record are both the negotiated rate.
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.get_stats`
      - ``list[PortStats]``
      - RX/TX bytes, packets and errors. Any counter a backend cannot read is
@@ -48,6 +52,25 @@ The operations
      - :py:obj:`~netgear_switch.models.MgmtIpConfig`
      - Address, netmask, gateway, DHCP-or-static mode, and the switch's base
        MAC.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.get_hostname`
+     - ``str``
+     - The switch's configured host name.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.get_users`
+     - ``list[SwitchUser]``
+     - Local login accounts. ``access_mode`` is the switch's own wording for
+       the account, kept verbatim because it differs by *face*, not just by
+       firmware: asked over the CLI the same admin account reads
+       ``Privilege-15`` on one image and ``Read/Write`` on another, while both
+       switches' web UIs call it ``Super User``. The normalised ``privileged``
+       flag beside it agrees across all three.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.get_services`
+     - ``list[ServiceStatus]``
+     - Whether http, https, telnet and ssh are enabled, and on which port
+       where the firmware reports one.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.get_syslog`
+     - :py:obj:`~netgear_switch.models.SyslogConfig`
+     - Whether remote logging is on, the local source port, and the configured
+       collectors.
 
 Not every model serves every one of these on every backend.
 :doc:`../models/support` has the complete grid, and
@@ -58,8 +81,13 @@ Absent data is ``None``, never a substitute
 
 A field a backend genuinely cannot read stays ``None``:
 
-* ``PortStatus.description`` is ``None`` on NSDP and HTTP backends, which have
-  no ``ifAlias`` equivalent — not ``""``.
+* ``PortStatus.description`` is ``None`` where the backend has no ``ifAlias``
+  equivalent — not ``""``. NSDP is **not** such a backend: tag 0xB000 carries
+  the operator's label and was cross-checked byte-for-byte against three real
+  GS110EMX units' own "Port Description" column, so it fills this field like
+  SNMP's ifAlias does. ``PortStatus.name`` is the opposite way round there:
+  NSDP reports a port NUMBER and no interface identifier, so ``name`` is None
+  over NSDP while SNMP gives ``1/0/1`` and the web UI ``g1``.
 * ``PoEStatus.power_mw`` is ``None`` on a switch with no vendor power column
   (the GS728TPP serves everything from standard MIBs and has no such column) —
   not ``0``.

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/guide/writing.rst

@@ -23,6 +23,16 @@ The operations
        wait for it to deliver again.
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.clear_poe_fault`
      - Clear a latched PoE fault on a port.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_port_description`
+     - Set or clear a port's label. Pass ``""`` to clear it.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_port_speed`
+     - Force a port's speed and duplex, or restore auto-negotiation. See
+       :ref:`speed-vs-negotiated` — the field this write verifies against is
+       *not* ``PortStatus.speed_mbps``.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_flow_control`
+     - Turn IEEE 802.3x flow control on or off for a port. CLI only — no web
+       UI captured so far carries a control for it, including the one whose
+       ports page *reports* the field.
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_pvid`
      - Set a port's PVID (native VLAN).
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_vlan_membership`
@@ -33,6 +43,10 @@ The operations
      - Delete a VLAN.
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_mgmt_ip`
      - Set the management address, netmask and gateway.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_hostname`
+     - Set the switch's host name.
+   * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.set_syslog_enabled`
+     - Turn remote logging on or off. Does not change the collector list.
    * - :py:obj:`~netgear_switch.sync_api.SyncSwitch.upload_certificate` / :py:obj:`~netgear_switch.sync_api.SyncSwitch.upload_certificate_scp`
      - Install an HTTPS server certificate — over the web UI, or by FASTPATH
        ``copy scp://``.
@@ -118,6 +132,58 @@ is here because it explains why the same call can behave differently across two
 switches from the same family, and why this project refuses to extrapolate
 between SKUs.
 
+.. _speed-vs-negotiated:
+
+Configured speed is not negotiated speed
+----------------------------------------
+
+``set_port_speed`` writes the port's *configuration*; :py:obj:`~netgear_switch.models.PortStatus`
+reports both that and the result, in two separate fields:
+
+* ``speed_config`` — a :py:obj:`~netgear_switch.models.PortSpeed`: what the port is **set** to
+  (``show port``'s "Physical Mode" column). Answers even while the link is down.
+* ``speed_mbps`` / ``full_duplex`` — what the link actually **negotiated**
+  ("Physical Status"). ``None`` while the link is down, because a down port has
+  negotiated nothing.
+
+They are separate because they genuinely disagree, and disagree hardest exactly
+where this library operates. A port forced to 100 Mbit/s with no cable in it
+reports ``speed_config=PortSpeed.forced(100, full_duplex=True)`` and
+``speed_mbps=None``. ``set_port_speed`` verifies itself against the first;
+verifying against the second would mean a write to any link-down port could
+never be confirmed.
+
+.. code-block:: python
+
+   from netgear_switch import PortSpeed
+
+   switch.set_port_speed(8, PortSpeed.forced(100, full_duplex=True), force=True)
+   switch.set_port_speed(8, PortSpeed.auto(), force=True)   # and back
+
+**The two backends disagree about a forced 1000, and both are right.**
+
+*Over the CLI*, asking for one raises :py:obj:`~netgear_switch.errors.CliCommandError` before
+anything is sent. 1000BASE-T requires auto-negotiation, and the FASTPATH
+grammar encodes that by leaving 1000 out of its forced ``speed`` command
+entirely while keeping it among ``speed auto``'s advertised rates.
+
+*Over the GoAhead web UI* (GS728TPP) it is accepted, because that page's own
+Speed control offers "1000M Full Duplex" — and the live switch really does run
+its four SFP uplinks that way. Fibre 1000BASE-X carries no such requirement.
+Harmonising the two into a single rule would have made one of them wrong about
+real hardware, so each backend answers for its own device.
+
+Which *other* rates are available differs the same way, and for the same
+reason — the PHY, not the firmware:
+
+* **CLI**: no rate table is kept at all. A 1G copper port offered 10/100/10G
+  while a 10GBASE-T port on another model offered 100/10G, so the library sends
+  what you ask for and surfaces the switch's own ``% Invalid input`` as
+  ``CliCommandError``.
+* **HTTP**: the page publishes its choices as a dropdown, so the library
+  validates against that captured list (10/100 half or full, 1000 full, Auto)
+  and refuses anything else with :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError`.
+
 Certificates
 ------------
 

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/index.rst

@@ -75,12 +75,13 @@ follows.
 What this library gives you
 ---------------------------
 
-**The same operations on every protocol a switch speaks.** Every read and every
-write is implemented across SNMP, NSDP, the web UI and the FASTPATH CLI, so the
-*caller* picks — useful when SNMP writes are locked down, or when the web port
-is all a firewall allows. Reading VLANs over SNMP, HTTP and SSH returns the same
-values, and the tests assert it. Where a gap remains, it is listed in
-:doc:`models/support`, with the reason.
+**One set of operations, on as many of a switch's protocols as it can serve.**
+The same API drives SNMP, NSDP, the web UI and the FASTPATH CLI, so the *caller*
+picks — useful when SNMP writes are locked down, or when the web port is all a
+firewall allows. Reading VLANs over SNMP, HTTP and SSH returns the same values,
+and the tests assert it. Where a backend cannot serve an operation, the library
+refuses by name instead of quietly answering over a different protocol, and
+:doc:`models/support` records which combinations those are and why.
 
 **Plus switches, not only managed ones.** The GS110EMX, GS305EP and GS105PE have
 no SNMP agent at all; they are driven over NSDP, an undocumented UDP protocol

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/models/gs305ep.rst

@@ -13,6 +13,22 @@ At a glance
 
 .. ngsw-model-facts:: gs305ep
 
+**Not captured from hardware.** This is the one model here with no device
+capture and no live run: every unit in this fleet (10.1.5.28-.30) was powered
+off when the attempt was made. What it *is* grounded in is two independent
+implementations that drive these switches — ``py_netgear_plus`` for the
+merge-hash login and the PoE/VLAN CGI paths, and ``netgear-smp-vlan`` for the
+``8021qCf.cgi``/``8021qMembe.cgi``/``portPVID.cgi`` field shapes and the
+1=untagged/2=tagged/3=excluded wire codes, observed on a GS105PE.
+
+So the page shapes are grounded, but the *values* are not: the mock seed is
+hand-invented (:py:func:`~netgear_switch.virtual.seed.seed_gs305ep` says so) and
+the web-UI fixtures under ``tests/fixtures/http/gs305ep_*.html`` each carry an
+``UNVERIFIED-pending-capture: synthetic`` marker. Treat behaviour recorded here
+as the documented shape, not as observed values — and see
+:doc:`gs105pe`, whose read paths turned out NOT to be shareable with this model
+even though the two do share a login scheme.
+
 Seed: :py:func:`~netgear_switch.virtual.seed.seed_gs305ep`.
 
 What works, over which protocol

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/models/index.rst

@@ -7,8 +7,13 @@ that registry at documentation build time, so it cannot drift from the code.
 
 .. ngsw-model-table::
 
-Every model listed above is backed by a real device capture or a live run
-against the hardware. :py:func:`~netgear_switch.registry.get_model` resolves a key — or
+Every model listed above is backed by evidence, and each model's own page says
+which kind. All but one are a device capture or a live run against the
+hardware. The **GS305EP is the exception**: its support is grounded in two
+independent implementations that drive these switches — ``py_netgear_plus``
+and ``netgear-smp-vlan``, the latter observed against a GS105PE — and no
+GS305EP has been captured, so its mock seed and web-UI fixtures are marked
+synthetic in the source. :py:func:`~netgear_switch.registry.get_model` resolves a key — or
 an alias, such as ``s3300`` — to the record; ``ngsw models`` prints the whole
 registry, including the entries these tables leave out, named below.
 

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/models/m4300-16x.rst

@@ -32,15 +32,17 @@ the port and the TLS flag, so :py:meth:`~netgear_switch.sync_api.SyncSwitch.get_
 with ``backend=Backend.HTTP`` reaches it with no special handling from the
 caller.
 
-**Its firmware requires a ``Referer`` header on every POST.** The same body
-returns 403 without one and 200 with it — a difference isolated live, then
-reproduced by the mock's HTTP face so the requirement cannot regress.
-
-**The VLAN-write dialect was settled by measurement, not by family.** This
-firmware *does* accept some Q-BRIDGE egress writes that the -24X refuses, so the
-inference from its sibling could not be trusted even though it happened to land
-on the right answer. An A/B/A on port 1/0/1, issuing byte-identical writes while
-flipping only that one port's mode, gave:
+**Its firmware requires an ``Origin`` header alongside the ``Referer`` on every
+POST.** A ``Referer`` alone is not enough: the same body returns 403 with only
+the Referer and 200 once Origin accompanies it, on pages whose ``GET`` returns
+200 — isolated live, then reproduced by the mock's HTTP face so the requirement
+cannot regress.
+
+**The VLAN-write dialect was settled by measurement, not by family.** The
+tempting reading — that this firmware simply accepts Q-BRIDGE egress writes the
+-24X refuses — is not what is happening, and the measurement says so. An A/B/A
+on port 1/0/1, issuing byte-identical writes while flipping only that one port's
+mode, gave:
 
 .. code-block:: text
 
@@ -49,11 +51,14 @@ flipping only that one port's mode, gave:
    access  → commitFailed              general → noError
 
 ``dot1qVlanStaticEgressPorts`` is writable only while **no interface on the
-switch** is in access mode — switch-wide, not per-VLAN. Since an untagged
-membership write is expressed *as* access mode, the standard dialect would
-disable itself on first use. So this SKU belongs on ``fastpath_switchport``
-after all — now for a reason rather than a guess. The full account is in
-:doc:`../guide/principles`.
+switch** is in access mode — switch-wide, not per-VLAN, and that rule is the
+same on both firmwares. The -24X looks different only because 21 of its 24 ports
+are in access mode, so its column is never writable; nothing about the two
+images differs here. Since an untagged membership write is expressed *as* access
+mode, the standard dialect would disable itself on first use, so this SKU
+belongs on ``fastpath_switchport`` after all — now for a reason rather than a
+guess, and for a reason that is a precondition rather than a firmware quirk. The
+full account is in :doc:`../guide/principles`.
 
 Protocols
 ---------

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/models/support.rst

@@ -93,6 +93,18 @@ restating them. A refusal falls into one of three kinds:
     most likely to move, because a page that exists but has not been found yet
     looks exactly the same from here.
 
+**The device's agent does not implement that operation.**
+    The protocol defines it, the hardware has it, and the switch still refuses.
+    The GS728TPP's SNMP agent will not create a VLAN: every documented RowStatus
+    mechanism — ``createAndGo`` alone, ``createAndGo`` carrying
+    ``dot1qVlanStaticName`` in one PDU, ``createAndWait`` → name → ``active``,
+    setting the name column alone, and ``createAndGo`` with an egress PortList —
+    is answered ``inconsistentValue``. That it is the agent and not the table is
+    shown by what the same firmware *does* accept: an existing VLAN's membership
+    columns, ``dot1qPvid``, and ``destroy(6)``, while its web UI creates a VLAN
+    without complaint. So VLAN creation on that model is an HTTP operation, and
+    the refusal names the backend that does work.
+
 What is *not* on this list is "not implemented yet". A backend that could serve
 an operation but does not is a bug in this library, and is fixed rather than
 documented.

{python_netgear_switch_library-0.0.post360 → python_netgear_switch_library-0.0.post404}/docs/protocols/nsdp.rst

@@ -104,7 +104,9 @@ Cross-checked against other implementations
 
 The v2 fold reproduces ``go-nsdp``'s own test vector byte for byte, and two
 independent third-party tools decoded the mock's packets. ProSafeLinux decodes
-both mock switches completely, with every value matching the seed; the C
+the GS110EMX and GS105PE mocks completely, with every value matching the seed
+(the third NSDP model, the GS305EP, is seeded from invention rather than a
+capture, so decoding it would prove nothing); the C
 implementation ``ngadmin`` validated the header and surfaced a real four-byte
 sequence-number bug, since fixed.