###################################################################
For most up to date and thorough information regarding MCMS PON Manager setup,
Please reference the relevant version release notes (TN035)

###################################################################
Copyright (c) 2025, Ciena Corporation
All rights reserved.

See the following additional documents for more information on the MCMS PON Manager:
    - Tibit Tech Note TN035 MCMS PON Manager User Guide and Release Notes.

Install Steps
-------------
Use the following steps to install the MCMS Pon Manager.
Ensure that you have execute/root permissions

1. Open shell in root directory of Pon Manager application

    NOTE - Upgrading from R1.2.X and earlier:
        If running a PON Manager version older than R1.3.0, you must run the uninstall script: 'legacy_uninstall.py' before installing R1.3.0 or newer.

    NOTE - Upgrading from R3.0.X and earlier:
        After upgrading from version R3.0.X to R3.1.0 or later, users are encouraged to run two scripts, 'merge_collections.py' and 'drop_collections.py', that will allow them to see data collected prior to the upgrade for both system logs and statistics.
        Follow these directions to safely transfer your data to the new database schema. Be sure and perform these steps AFTER upgrading the PON Manager and PON Controller to R3.1.0:
        1. First run the merge_collections.py script to store your data in the new collections.
            - Usage: ./merge_collections.py --db <mongodb_uri>/<database>. Example: ./merge_collections.py --db mongodb://10.1.10.111:27017/tibit_pon_controller
        2. Ensure data transferred successfully by seeing this message: '************* Collection transfers sucessful! *************'. You can also check by looking at the device statistics and system logs tabs in the MCMS PON Manager and ensuring data is being retrieved from prior to upgrading.
        3. Run the 'drop_collections.py' script to remove the old collections from the database. This will clean up unused collections and improve database performance.
            - Usage: ./drop_collections.py --db <mongodb_uri>/<database>. Example: ./drop_collections.py --db mongodb://10.1.10.111:27017/tibit_pon_controller

2. (RECOMMENDED, OPTIONAL) Configure self-signed certificate

    NOTE - It is recommended to deploy a properly-signed certificate for your PON Manager Web Server
    - By default, PON Manager will deploy using HTTPS utilizing a self-signed certificate created during installation. THIS IS NOT SAFE FOR ANY USE-CASE OTHER THAN TESTING/LAB USE.
    - Optionally, you may configure a self-signed certificate that will be created and used by providing your own certificate config file. You may refer to the default config file provided within this package directory.
    - The config file must include the following two sections;
        1. [req_distinguished_name]
            - countryName = Country code. Ex. US (United States), CA (Canada), MX (Mexico), etc
            - ST :                      State or providence
            - localityName :            City or locality
            - organizationName :        Name of organization
            - organizationalUnitName :  Name of group/unut
            - CN :                      Fully Qualified Doamin Name of system

        2. [alt_names]
            - DNS.*number*              Name to access web server. You can configure mulitple names by adding more 'DNS.x' lines with increasing numbers in place of the 'x'.
            - IP.*number*               IP of machine. You can configure mulitple interfaces by adding more 'IP.x' lines with increasing numbers in place of the 'x'. Ex. IP.1 = 127.0.0.1 IP.2 =10.1.10.225

3. Use one of the following commands to install PON Manager:

(Ubuntu)
    $ 'sudo apt-get install ./tibit-ponmgr_R5.2.0_all.deb'  # Creates default certificate
    $ 'sudo TIBIT_PONMGR_CERT_REQ=/path/to/cert.conf apt-get install ./tibit-ponmgr_R5.2.0_all.deb'  # Creates custom certificate using the config file that was given

(Red Hat)
    $ 'sudo dnf install ./tibit-ponmgr-R5.2.0-1.el8.x86_64.rpm' # Creates default certificate


Upgrade Steps
-------------
This process upgrades the MCMS PON Manager version without uninstalling the software.
If upgrade has new versions of configuration files, current version of config files won't be replaced,
but a copy of the new version of config files will be installed (example user_database.json.rpmnew)

(Ubuntu)
    $ 'sudo apt-get install ./tibit-ponmgr_R5.2.0_all.deb'

(Red Hat)
    $ 'sudo dnf install ./tibit-ponmgr-R5.2.0-1.el8.x86_64.rpm'


Uninstall Steps
---------------
The uninstall process completely removes the /etc/tibit/ponmgr and /opt/tibit/ponmgr directories from the file system.
Optionally, the MCMS PON Manager configuration files may be kept.

To Uninstall (keep config files):
- This will remove the Pon Manager, but will leave configuration files behind

(Ubuntu)
    $ "sudo apt-get remove tibit-ponmgr"

To Uninstall (remove config files):
- This will remove the Pon Manager, and will also remove configuration files

(Ubuntu)
    $ "sudo apt-get remove tibit-ponmgr --purge"

(RedHat)
    $ "sudo dnf remove tibit-ponmgr"
NOTE - If a scriptlet fails and prevents uninstall, run: 'sudo dnf --setopt=tsflags=noscripts remove tibit-ponmgr'


Configuring the Software
------------------------
To Configure:
    First: Navigate to the directory: /etc/tibit/ponmgr

    1. user_database.json | Stores info for database to be used for user authentication
        - host : Host/IP of your mongoDB server hosting your user database
        - name : Name of your user database. (IF it doesn't exist, it will be created)
        - port : MongoDB Port
        - auth_enable : Boolean value determining if the MongoDB server at host:port is using authentication
        - auth_db : Name of your MongoDB user database. (Used when auth_enabled = true)
        - username : The username of the MongoDB user to authenticate with. (Used when auth_enabled = true)
        - password : The password of the MongoDB user specified by username. (Used when auth_enabled = true)
        - tls_enable : Boolean value specifying whether the MongoDB server at host:port is using encryption
        - ca_cert_path : The local path to the encryption certificate
        - db_uri : Raw MongoDB connection uri. All other fields are ignored if this is used
        - dns_srv : Boolean to determine if the MongoDB server is using a DNS seed list
        - replica_set_enable : Boolean value used to determine if the MongoDB server is running as a replica set
        - replica_set_name : The name of the MongoDB replica set. (Used when replica_set_enable = true)
        - replica_set_hosts : List of hosts to be used as the MongoDB replica set. (Used when replica_set_enable = true)
        - django_key : Randomized string used for internal MCMS encoding operations.

    2. databases.json | Stores list of all available PON databases in Pon Manager
        - Default:
            - host : Host/IP of your mongoDB server hosting your PON Data
            - name : Name of your Pon Data database (Ex. tibit_pon_controller)
            - port : MongoDB Port
            - auth_enable : Boolean value determining if the MongoDB server at host:port is using authentication
            - auth_db : Name of your MongoDB user database. (Used when auth_enabled = true)
            - username : The username of the MongoDB user to authenticate with. (Used when auth_enabled = true)
            - password : The password of the MongoDB user specified by username. (Used when auth_enabled = true)
            - tls_enable : Boolean value specifying whether the MongoDB server at host:port is using encryption
            - ca_cert_path : The local path to the encryption certificate
            - db_uri : Raw MongoDB connection uri. All other fields are ignored if this is used
            - dns_srv : Boolean to determine if the MongoDB server is using a DNS seed list
            - replica_set_enable : Boolean value used to determine if the MongoDB server is running as a replica set
            - replica_set_name : The name of the MongoDB replica set. (Used when replica_set_enable = true)
            - replica_set_hosts : List of hosts to be used as the MongoDB replica set. (Used when replica_set_enable = true)

    3. recovery_email_configuration.json | Configures SMTP Email server for sending user password recovery emails
        host : The host to use for sending email
        port : Port to use for the SMTP server defined above (string)
        use_tls : Use TLS connection. Requires supported host and port (boolean in string format)
        user : username for the SMTP server
        password : password for user

    4. (OPTIONAL) tibitdev-web.conf | Configures Apache virtualhost of webpage. Can change SSL certificates being used
        SSLCertificateFile : Path to SSL certificate
        SSLCertificateKeyFile : Path to SSL Key file

    5. (OPTIONAL) tibitdev-api.conf | Configures Apache virtualhost of REST API. Can change SSL certificates being used
        SSLCertificateFile : Path to SSL certificate
        SSLCertificateKeyFile : Path to SSL Key file

    6. Restart Apache
        - $ 'sudo systemctl restart apache2'


Running the Software
--------------------
- In browser, navigate to; https://*ipofserver*
    Examples:
        - https://10.1.10.255
        - https://127.0.0.1

- Web pages are served from default port 80. In browser, navigate to; https://ipofserver
- API is served from specified port. https://ipofserver:port
- MongoDB default port is 27017. Default db name is tibit_pon_controller

Currently Supported Browsers:
    - FireFox
    - Chrome
