Development: explain ApiMutableServiceControllerBase and refer to examples from controller documentation (controller.rst contains the concepts, examples are more suited to explain the use in this case)

source/development/examples.rst

@@ -7,4 +7,6 @@ Examples
    :titlesonly:
    :glob:
 
-   examples/*
+   examples/helloworld
+   examples/using_grids
+   examples/api_enable_services

source/development/examples/api_enable_services.rst

@@ -0,0 +1,125 @@
+=============================
+API enable standard services
+=============================
+
+OPNsense contains a simple wrapper which handles standard service actions like starting and stopping services.
+For this example, we assume the HelloWorld example is created and the model exists.
+
+Prerequisites
+--------------------
+
+The HelloWorld example forms the basis for this one, please make sure you read and try it first before starting with
+this one.
+
+
+Configd actions
+--------------------
+
+
+Since the example didn't contain a service, we're going to extend the configd template first.
+Edit :code:`/usr/local/opnsense/service/conf/actions.d/actions_helloworld.conf` and expand with the following sections:
+
+::
+
+    [start]
+    command:exit 0
+    parameters:
+    type:script
+    message:hello world service start
+
+    [stop]
+    command:exit 0
+    parameters:
+    type:script
+    message:hello world service stop
+
+    [restart]
+    command:exit 0
+    parameters:
+    type:script
+    message:hello world service restart
+
+    [reload]
+    command:exit 0
+    parameters:
+    type:script
+    message:hello world service restart
+
+    [status]
+    command: echo "hello world is running"
+    parameters:
+    type:script_output
+    message:hello world service status
+
+Next restart configd using :code:`service configd restart` and test these new calls using the following commands
+
+::
+
+    # configctl helloworld start
+    OK
+    # configctl helloworld stop
+    OK
+    # configctl helloworld status
+    hello world is running
+    # configctl helloworld restart
+    OK
+
+
+Our template only simulates a service, it doesn't actually do anything (:code:`exit 0`).
+
+Update the service controller
+---------------------------------
+
+
+Next we change the existing controller to use :code:`ApiMutableServiceControllerBase`, which links the existing model to the service callouts defined.
+The :code:`testAction` used in the HelloWorld example is left out to avoid confusion.
+
+.. code-block:: php
+    :caption: /usr/local/opnsense/mvc/app/controllers/OPNsense/HelloWorld/Api/ServiceController.php
+
+    use OPNsense\Base\ApiMutableServiceControllerBase;
+
+    class ServiceController extends ApiMutableServiceControllerBase
+    {
+        protected static $internalServiceClass = '\OPNsense\HelloWorld\HelloWorld';
+        protected static $internalServiceTemplate = 'OPNsense/HelloWorld';
+        protected static $internalServiceEnabled = 'general.enabled';
+        protected static $internalServiceName = 'helloworld';
+
+        protected function reconfigureForceRestart()
+        {
+            return 0;
+        }
+    }
+
+
+The  service above defines the following static variables:
+
+* $internalServiceClass
+    * reference the model class, which is used to determine if this service is enabled (links the model to the service)
+* $internalServiceTemplate
+    * before starting the service it will call configd to generate configuration data, in this case it would execute the equivalent of :code:`configctl template reload OPNsense/HelloWorld` on the console
+* $internalServiceEnabled
+    * Which section of the model contains a boolean defining if the service is enabled (general.enabled)
+* $internalServiceName
+    * refers to the action template, where it can find start/stop/restart/status/reload actions (actions_helloworld.conf)
+
+
+The :code:`reconfigureForceRestart` overwrite tells the controller if it should always stop the service before trying a start, some
+services can be signaled to do a reconfigure without stopping.
+
+
+Endpoints
+---------------------------------
+
+When deploying this controller into the HelloWorld module it would expose the following endpoints
+
+.. csv-table::
+   :header: "Method", "Endpoint"
+   :widths: 4, 100
+
+   "``POST``","/api/helloworld/service/stop"
+   "``POST``","/api/helloworld/service/start"
+   "``POST``","/api/helloworld/service/restart"
+   "``POST``","/api/helloworld/service/reconfigure"
+   "``GET``","/api/helloworld/service/status"

source/development/frontend/controller.rst

@@ -99,3 +99,12 @@ post request to /api/sample/test/echo, using jQuery:
                 },
                 data:{message:"test message"}
             });
+
+
+.. Tip::
+
+    OPNsense ships with two standard controllers to incorporate default action scenario's, such as mutating models
+    and restarting services. These can be found in our repository `here <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/controllers/OPNsense/Base/>`__
+    and are named :code:`ApiMutableModelControllerBase`, :code:`ApiMutableServiceControllerBase`. Both extend :code:`ApiControllerBase`
+    as described in this chapter. The mutable model controller is explained in more detail in :doc:`using grids <../examples/using_grids>`, the
+    service controller is explained in :doc:`api enable services <../examples/api_enable_services>`