Docs fixes

docs/administration-faq.rst

@@ -3,29 +3,62 @@
 Administration FAQ
 ==================
 
-.. topic:: Duplicate log entries when using :func:`log()` function
+.. _administration-faq-duplicate-log-entries:
+
+Duplicate log entries when using :func:`log()` function
+-------------------------------------------------------
 
 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).
+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).
 
 To illustrate with an example, consider the following script:
 
 .. code:: javascript
 
+  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
+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.

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

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
+<administration-faq-duplicate-log-entries>`.
+
 .. _path-format:
 
 Path format