From e31d74bd452b26e42436773dd414262552b794b2 Mon Sep 17 00:00:00 2001 From: Zaid Abdulla Date: Fri, 11 Oct 2019 00:40:55 -0700 Subject: [PATCH] Docs fixes --- docs/administration-faq.rst | 75 ++++++++++++++++++++++++++----------- docs/installation-guide.rst | 19 ++++++---- docs/provisions.rst | 8 ++++ 3 files changed, 74 insertions(+), 28 deletions(-) diff --git a/docs/administration-faq.rst b/docs/administration-faq.rst index 9fa880d..5d1d15d 100644 --- a/docs/administration-faq.rst +++ b/docs/administration-faq.rst @@ -3,29 +3,62 @@ Administration FAQ ================== -.. topic:: Duplicate log entries when using :func:`log()` function +.. _administration-faq-duplicate-log-entries: - Because GenieACS uses a full fledged scripting language for device - configuration, the only way to guarantee that it has satisfied the 'desired - state' is by repeatedly executing the script until there's no more - discrepancies with the current device state. Though it may seem like this - will cause duplicate requests going to the device, this isn't actually the - case because device configuration are stated declaratively and that the - scripts themselves are pure functions in the context of a session (e.g. - Date.now() always returns the same value within the session). +Duplicate log entries when using :func:`log()` function +------------------------------------------------------- - To illustrate with an example, consider the following script: +Because GenieACS uses a full fledged scripting language for device +configuration, the only way to guarantee that it has satisfied the 'desired +state' is by repeatedly executing the script until there's no more +discrepancies with the current device state. Though it may seem like this will +cause duplicate requests going to the device, this isn't actually the case +because device configuration are stated declaratively and that the scripts +themselves are pure functions in the context of a session (e.g. Date.now() +always returns the same value within the session). - .. code:: javascript +To illustrate with an example, consider the following script: - declare("Device.param", null, {value: 1}); - commit(); - declare("Device.param", null, {value: 2}); +.. code:: javascript - This will set the value of the 'Device.param' to 1, then to 2. Then as the - script is run again the value is set back to 1 and so on. A stable state will - never be reached so GenieACS will execute the script a few times until it - gives up and throws a fault. This is an edge case that should be avoided. A - more typical case is where the script is run once or twice. Essentially if an - execution doesn't result in any request to the CPE or a change in the data - model then a stable state is deemed to have been reached. + log("Executing script"); + declare("Device.param", null, {value: 1}); + commit(); + declare("Device.param", null, {value: 2}); + +This will set the value of the 'Device.param' to 1, then to 2. Then as the +script is run again the value is set back to 1 and so on. A stable state will +never be reached so GenieACS will execute the script a few times until it gives +up and throws a fault. This is an edge case that should be avoided. A more +typical case is where the script is run once or twice. Essentially if an +execution doesn't result in any request to the CPE or a change in the data +model then a stable state is deemed to have been reached. + +Configurations not pushed to device after factory reset +--------------------------------------------------------- + +After a device is reset to its factory default state, the cached data model in +GenieACS's database needs to be invalidated to force rediscovery. Ensure the +following lines are called on ``0 BOOTSTRAP`` event: + +.. code:: javascript + + const now = Date.now(); + + // Clear cached data model to force a refresh + clear("Device", now); + clear("InternetGatewayDevice", now); + + +Most device parameters are missing +---------------------------------- + +For performance reasons (server, client, and network), GenieACS by default only +fetches parts of the data model that are necessary to satisfy the declarations +in your provision scripts. Create declarations for any parameters you need +fetched by default. + +If you're unsure and want to explore the available parameters exposed by the +device, refresh the root parameter (e.g. ``InternetGatewayDevice``) from +GenieACS's UI. You typically only need to do that one time for a given CPE +model. diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst index 810ab8a..8ed2d0e 100644 --- a/docs/installation-guide.rst +++ b/docs/installation-guide.rst @@ -68,7 +68,7 @@ Configure systemd .. code:: bash - GENIEACS_CWMP_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-cmwp-access.log + GENIEACS_CWMP_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-cwmp-access.log GENIEACS_NBI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-nbi-access.log GENIEACS_FS_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-fs-access.log GENIEACS_UI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-ui-access.log @@ -101,11 +101,16 @@ Configure systemd :file:`/var/log/genieacs/` while process logs go to *journald*. Use ``journalctl`` command to view process logs. + .. attention:: + + If the command :command:`systemctl edit --force --full` fails, you can + create the unit file manually. + 1. Run the following command to create ``genieacs-cwmp`` service: .. code:: bash - sudo systemctl edit --force genieacs-cwmp + sudo systemctl edit --force --full genieacs-cwmp Then paste the following in the editor and save: @@ -127,7 +132,7 @@ Configure systemd .. code:: bash - sudo systemctl edit --force genieacs-nbi + sudo systemctl edit --force --full genieacs-nbi Then paste the following in the editor and save: @@ -149,7 +154,7 @@ Configure systemd .. code:: bash - sudo systemctl edit --force genieacs-fs + sudo systemctl edit --force --full genieacs-fs Then paste the following in the editor and save: @@ -171,7 +176,7 @@ Configure systemd .. code:: bash - sudo systemctl edit --force genieacs-ui + sudo systemctl edit --force --full genieacs-ui Then paste the following in the editor and save: @@ -191,11 +196,11 @@ Configure systemd .. topic:: Configure log file rotation using logrotate - Save the following under :file:`/etc/logrotate.d/genieacs` + Save the following as :file:`/etc/logrotate.d/genieacs` .. code:: - /var/log/genieacs/*.{log,yaml} { + /var/log/genieacs/*.log /var/log/genieacs/*.yaml { daily rotate 30 compress diff --git a/docs/provisions.rst b/docs/provisions.rst index 06f6216..e84a3f2 100644 --- a/docs/provisions.rst +++ b/docs/provisions.rst @@ -128,6 +128,14 @@ script filename while second argument is the function name within that script. Any remaining arguments will be passed to that function. See :ref:`extensions` for more details. +``log(message)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prints out a string in genieacs-cwmp's access log. It's meant to be used for +debugging. Note that you may see multiple log entries as the script can be +executed multiple times in a session. See :ref:`this FAQ +`. + .. _path-format: Path format