============================================================
  Z9 Open - Niagara Module Installation
============================================================

Z9 Open (module "z9open", file "z9open-rt.jar") is a Niagara module that
presents a Niagara JACE to a Z9/Flex access-control system as a controller.
It reads the JACE's Enterprise Security access model and bridges it to
Z9/Flex. It makes no access decisions of its own.

This package contains these files:

  z9open-rt.jar                 The Niagara module to install (code-signed).
  z9open-doc.jar                Workbench help for the module (code-signed).
                                Optional: copy it into the "modules" folder of the
                                PC WORKBENCH installation you engineer with (not
                                the JACE) and restart Workbench. The module then
                                appears under Help > Contents, and Help > Guide On
                                Target works on the Z9OpenService.
  README.txt                    This file.
  z9security-codesign.crt       The Z9 code-signing certificate. NOT needed for a
                                normal install (the module loads without it). Kept
                                only for stations hardened to High module
                                verification (see "A note on signing" at the end).


------------------------------------------------------------
  Requirements
------------------------------------------------------------

  - Niagara N4 4.6 (this build is compiled against 4.6.96.28) on the JACE.
  - Enterprise Security on the JACE. z9open depends on these access-control
    runtime modules being present: "entsec", "accessDriver", and the Orion
    access driver "orion". A controller already running Z9/Flex access control
    will have them. If any are missing the station will refuse to load z9open
    with a "dependency failed" error (this is NOT a signing problem).
  - Niagara Workbench with platform access to the JACE.

  No code-signing certificate is required. The module declares its needs as Niagara
  permission GROUPS (NETWORK_COMMUNICATION, MANAGE_EXECUTION, SYSTEM_PROPERTIES,
  LOGGING), which load without a signature check -- so there is nothing to import on
  a normal station. (The jar is still signed; that only matters if a station is
  hardened to High module verification -- see "A note on signing" at the end.)


------------------------------------------------------------
  Step 1 - Add the module to Workbench
------------------------------------------------------------

  1. Copy  z9open-rt.jar  into the  "modules"  folder of your Niagara
     installation.
       (example path -- use your own install location:
        C:\Niagara\Niagara-4.6.x\modules)
  2. Restart Workbench so it picks up the new module.


------------------------------------------------------------
  Step 2 - Install the module on the JACE
------------------------------------------------------------

  1. In Workbench, open a Platform connection to the JACE:
       File > Open > Open Platform  (or the Open Platform toolbar button),
     then enter the JACE's IP address and your PLATFORM credentials
     (the platform login, which may differ from the station login).
  2. Open the  Software Manager.
  3. Find  "z9open"  in the list. Confirm the Available version matches the jar
     you added in Step 1, set its action to  Install.
  4. Click  Commit.  The module transfers to the JACE ("Sending...") and the
     station restarts to load it.


------------------------------------------------------------
  Step 3 - Confirm the module loaded
------------------------------------------------------------

  1. Open  Application Director  (under the Platform node).
  2. Select the station and watch the console output as it restarts.
  3. You should see:    Module added "z9open-rt"
     and NO  "Error processing module file z9open"  and no dependency error.

  If you see  "dependency failed: ..."  the JACE is missing one of the required
  modules listed under Requirements -- install it / confirm Enterprise Security
  is present, then restart the station.


------------------------------------------------------------
  Step 4 - Add the Z9 Open service to the station
------------------------------------------------------------

  The service is added by dragging it from the z9open palette -- NOT from the
  Services "New" menu (Niagara does not list module service types there).

  1. Open the station (double-click it in the Nav tree and log in with the
     station credentials), then expand  Config > Services.
  2. Open the palette side bar:  Window > Side Bars > Palette.
  3. Click the  Open Palette  icon (the folder icon at the top of the palette
     pane), select  "z9open"  from the list, and click OK.
  4. Drag  "Z9 Open Service"  from the palette onto  Services.  Give it a name
     when prompted and click OK.
  5. The service starts on its own.


------------------------------------------------------------
  Step 5 - Connect to Z9/Flex
------------------------------------------------------------

The module presents the JACE as a controller to your Z9/Flex system. Register /
take the controller over from Z9/Flex the same way you would any controller.

Please note:

  - Once taken over, synchronization is bidirectional immediately: the JACE's
    doors and events report up to Z9/Flex, and Z9/Flex writes credentials,
    schedules, and access rights down to the JACE.

  - IMPORTANT: Z9/Flex becomes the ONLY source of access control on this JACE.
    Each time the service connects to Z9/Flex it DELETES every Enterprise
    Security cardholder, card (badge), access right, and card (Wiegand) format
    that was not created by Z9/Flex. Records enrolled directly on the JACE are
    permanently removed on the first connect and must be managed in Z9/Flex
    from then on. Schedules and holidays are not deleted, but any link you
    wired from a schedule (or threat level group) into a door strike's
    unlockSchedule, overrideSchedule, threatLevelGroup, or
    scheduleLockdownThreatLevel input is removed, so only Z9/Flex decides
    when a door unlocks on a schedule or locks down. Strike inputs such as
    unlockInput (e.g. a fire-alarm release) are not touched. This cannot be
    turned off.

    Before deleting anything, the service saves a copy of everything it is
    about to remove (cardholders, cards, access rights and who had them, card
    formats, and removed schedule links) as spreadsheet (CSV) files in a zip in
    the station's file space, under  z9flex/purge-archive/ . Download it from
    Workbench (station > Files). It contains cardholder names and card numbers:
    store it securely. If that copy cannot be saved, nothing is deleted.

  - The controller identifies itself by its network MAC address automatically;
    no controller ID needs to be entered. This identifier -- shown in Z9/Flex as
    the controller's serial number / MAC -- is taken from the MAC address of the
    JACE's FIRST Ethernet interface, and is used for identification only. If the
    JACE reaches Z9/Flex over its SECOND network interface, the address it
    connects from will not match the serial number / MAC shown; this apparent
    disagreement is expected and causes no problems.


------------------------------------------------------------
  Upgrading an existing installation
------------------------------------------------------------

To upgrade z9open to a newer version, repeat Step 2 (Software Manager > z9open,
action Install) with the new z9open-rt.jar. The station restarts to load it.
(If your station is hardened to High module verification, the signing note at
the end applies to the new jar too.)

  RECOMMENDED after any upgrade: perform a Controller Resync from Z9/Flex for
  this controller.

  A resync re-downloads and re-applies the controller's full configuration --
  credentials, schedules, access rights, and door settings -- under the new
  module version. This makes sure any change in how the new version applies
  configuration takes effect on the records already on the JACE, not only on
  configuration you edit afterward. It is safe to run at any time and does not
  interrupt access control.

  In Z9/Flex, open the controller and choose its Resync action (controller
  maintenance); allow a few seconds for the download to complete.


------------------------------------------------------------
  Troubleshooting - where to find the logs
------------------------------------------------------------

The station's log is the Application Director console output:

  1. In Workbench, open the Platform connection to the JACE.
  2. Double-click  Application Director.
  3. Select the station -- the lower pane streams its live console output (and
     recent history; scroll up to see earlier messages).

z9open's messages are logged under the  [z9open]  and  [z9open.probe]  log
categories.  Common ones and what they mean:

  - "awaiting takeover (no callback host yet); listening on takeover port N"
                                       -- normal before the controller has been
    taken over by Z9/Flex; the takeover listener is up and waiting.
  - "not provisioned; bridge not started"  -- normal; the outbound connection to
    Z9/Flex starts only after takeover.
  - "controllerId auto-detected ... MAC: ..."  -- normal.
  - "bridge started (...)"                     -- connected to Z9/Flex.
  - the  [z9open.probe]  block dumps this station's access-control records
    (people, badges, readers, access rights, ...) at startup -- read-only.

  NOTE on the takeover listener: it defaults to port 4443 (the station's own web
  server owns 443). If you see "the takeover listener is NOT running", check the
  "failed to start the takeover listener on port ..." line just above it for the
  cause (e.g. the port is in use).

The service's own  status  (top of its property sheet) should read  {ok}  once
it has started.

If the module did not load at all, the problem shows on the station's last
restart in Application Director (see Step 3): look for  "Error processing module
file z9open"  or  "dependency failed".


------------------------------------------------------------
  A note on signing (for reference)
------------------------------------------------------------

z9open declares its Java permissions as Niagara permission GROUPS
(<niagara-permission-groups>: NETWORK_COMMUNICATION, MANAGE_EXECUTION,
SYSTEM_PROPERTIES, LOGGING) rather than raw <java-permissions>. None of those groups
invoke the module-signing check, so on a normally-configured station the module
loads with no signature and no trusted certificate -- nothing to import.

We still sign z9open-rt.jar (with the self-signed "CN=Z9 Security" code-signing
cert) as good practice. That signature only comes into play if a station is
hardened to High module verification, where it validates every module's signature
against a trust anchor in the User Trust Store. Normal stations need none of this.

For such a station -- and only such a station -- import z9security-codesign.crt
(this package) into the User Trust Store in TWO separate places (it is two distinct
trust stores):

  1. The JACE's User Trust Store -- so the running station trusts the module at
     load. In Workbench: open a PLATFORM connection to the JACE, then
     Certificate Management > User Trust Store > Import.

  2. The Workbench computer's own User Trust Store -- so Workbench will validate
     and push the module to the JACE in the first place. In Workbench (no platform
     connection -- the local stores): Tools > Certificate Management > User Trust
     Store > Import.

Importing into one does not cover the other; a hardened install needs both.


------------------------------------------------------------
  Support
------------------------------------------------------------

  Z9 Security
  support@z9security.com
