[feature:gsoc26] Mass Commands

.github/workflows/ci.yml

@@ -5,13 +5,13 @@ on:
   push:
     branches:
       - master
+      - "gsoc26-*"
   pull_request:
     branches:
       - master
       - "1.1"
       - "1.2"
-      - "gsoc26-x509-certificate-generator-templates"
-      - "gsoc26-mass-commands"
+      - "gsoc26-*"
 
 jobs:
   build:
@@ -95,7 +95,7 @@ jobs:
         with:
           parallel: true
           format: cobertura
-          flag-name: python-${{ matrix.env.env }}
+          flag-name: python-${{ matrix.python-version }}-${{ matrix.django-version }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
           fail-on-error: false
 

docs/developer/extending.rst

@@ -354,6 +354,7 @@ Once you have created the models, add the following to your
     CONNECTION_CREDENTIALS_MODEL = "sample_connection.Credentials"
     CONNECTION_DEVICECONNECTION_MODEL = "sample_connection.DeviceConnection"
     CONNECTION_COMMAND_MODEL = "sample_connection.Command"
+    CONNECTION_BATCHCOMMAND_MODEL = "sample_connection.BatchCommand"
     SUBNET_DIVISION_SUBNETDIVISIONRULE_MODEL = "sample_subnet_division.SubnetDivisionRule"
     SUBNET_DIVISION_SUBNETDIVISIONINDEX_MODEL = "sample_subnet_division.SubnetDivisionIndex"
 

docs/user/intro.rst

@@ -70,6 +70,9 @@ e.g.:
 
 - Sending configuration updates.
 - :doc:`Executing shell commands <shell-commands>`.
+- :ref:`Executing mass commands <mass_commands>`: Run a command on
+  multiple devices at once, from the admin or with the :ref:`batch command
+  API <controller_batch_command_api>`.
 - Perform firmware upgrades via the additional :doc:`firmware upgrade
   module </firmware-upgrader/index>`.
 

docs/user/rest-api.rst

@@ -210,7 +210,7 @@ config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "config": {
@@ -225,7 +225,7 @@ the/their {id} from the config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "config": {
@@ -240,7 +240,7 @@ from the config of a device,
 
     curl -X PATCH \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'cache-control: no-cache' \
         -H 'content-type: application/json' \
         -H 'postman-token: b3f6a1cc-ff13-5eba-e460-8f394e485801' \
@@ -465,7 +465,7 @@ command type being executed.
 
     curl -X POST \
         http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/command/ \
-        -H 'authorization: Bearer yoursecretauthtoken' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "type": "custom",
@@ -481,6 +481,130 @@ Get Command Details
 
     GET /api/v1/controller/device/{device_id}/command/{command_id}/
 
+.. _controller_batch_command_api:
+
+Dry-Run Mass Command
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/execute/
+
+Returns the paginated list of devices that would be targeted without
+executing anything. Useful for previewing which devices are affected.
+
+**Query Parameters:**
+
+================ =========================================================
+Parameter        Description
+================ =========================================================
+``organization`` Organization UUID (optional for superusers; set
+                 automatically when ``group`` or ``location`` is provided)
+``type``         Command type (optional for dry-run)
+``input``        JSON input data for the command (optional for dry-run).
+                 Encode as a URL-encoded JSON object, e.g.
+                 ``?type=custom&input=%7B%22command%22%3A%22uptime%22%7D``
+``devices``      Repeated ``devices`` query parameter, each a device UUID
+                 (optional; when provided, ``group`` and ``location`` are
+                 ignored; all devices must belong to the same
+                 organization)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+================ =========================================================
+
+Execute a Mass Command
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    POST /api/v1/controller/batch-command/execute/
+
+Creates and executes a batch command on the targeted devices.
+
+**Request Parameters:**
+
+================ =========================================================
+Parameter        Description
+================ =========================================================
+``organization`` Organization UUID (optional for superusers; set
+                 automatically when ``group`` or ``location`` is provided)
+``type``         Type of command to execute (**required**)
+``input``        Input data for the command (**conditionally required** —
+                 depends on command type)
+``label``        A short label to identify this batch command
+                 (**required**)
+``notes``        Optional notes (optional)
+``devices``      List of device UUIDs (optional; when provided, ``group``
+                 and ``location`` are ignored; all devices must belong to
+                 the same organization)
+``group``        Device group UUID (optional)
+``location``     Location UUID (optional)
+================ =========================================================
+
+**Available Command Types:**
+
+See :ref:`controller_execute_command_api` for available command types and
+input formats.
+
+**Example payload:**
+
+.. code-block:: json
+
+    {
+        "organization": "org-uuid",
+        "type": "custom",
+        "input": {"command": "uptime"},
+        "label": "Check uptime"
+    }
+
+**Example request:**
+
+.. code-block:: shell
+
+    curl -X POST \
+        http://127.0.0.1:8000/api/v1/controller/batch-command/execute/ \
+        -H 'authorization: Bearer <token>' \
+        -H 'content-type: application/json' \
+        -d '{
+                "organization": "org-uuid",
+                "type": "custom",
+                "input": {"command": "uptime"},
+                "label": "Check uptime"
+            }'
+
+**Response:** ``201 Created`` with the batch command UUID.
+
+List Mass Commands
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/
+
+Returns a paginated list of batch commands with device count and skipped
+device information.
+
+Get Mass Command Detail
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/{id}/
+
+Returns detailed information about a batch command, including the list of
+targeted devices.
+
+List Mass Command Results
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    GET /api/v1/controller/batch-command/{id}/command/
+
+Returns the paginated list of commands the mass command created, with the
+status and output of each device. The commands of a device which was moved
+to another organization are only returned to superusers.
+
 List Device Groups
 ~~~~~~~~~~~~~~~~~~
 
@@ -603,7 +727,7 @@ You can create ``DeviceLocation`` object by using primary keys of existing
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
             "location": "f0cb5762-3711-4791-95b6-c2f6656249fa",
@@ -635,7 +759,7 @@ single request.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: application/json' \
         -d '{
                 "location": {
@@ -686,7 +810,7 @@ demonstrates creating both ``Location`` and ``FloorPlan`` objects.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F 'location.name=Via del Corso' \
         -F 'location.address=Via del Corso, Roma, Italia' \
@@ -716,7 +840,7 @@ plan for that location using this endpoint.
 
     curl -X PUT \
         http://127.0.0.1:8000/api/v1/controller/device/8a85cc23-bad5-4c7e-b9f4-ffe298defb5c/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F location=f0cb5762-3711-4791-95b6-c2f6656249fa \
         -F floorplan.floor=1 \
@@ -907,7 +1031,7 @@ in a single request.
 
     curl -X POST \
         http://127.0.0.1:8000/api/v1/controller/location/ \
-        -H 'authorization: Bearer dc8d497838d4914c9db9aad9b6ec66f6c36ff46b' \
+        -H 'authorization: Bearer <token>' \
         -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
         -F 'name=Via del Corso' \
         -F 'address=Via del Corso, Roma, Italia' \

docs/user/shell-commands.rst

@@ -5,6 +5,23 @@ Sending Commands to Devices
     :depth: 3
     :local:
 
+Single Device Commands
+----------------------
+
+Commands can be sent to one device at a time from the device detail page,
+as shown in the GIF below:
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/single_command_demo.gif
+    :target: https://github.com/openwisp/openwisp-controller/tree/docs/docs/single_command_demo.gif
+    :alt: Sending a single command
+
+Click the **Send Command** button, select the command type and fill in the
+required inputs. The command is sent to the device and its status is shown
+in the **Recent Commands** section of the device detail page.
+
+To send the same command to many devices at once, refer to
+:ref:`mass_commands`.
+
 Default Commands
 ----------------
 
@@ -41,6 +58,76 @@ shell commands, you can add new commands by following instructions in the
     You can also use the :ref:`REST API <controller_execute_command_api>`
     to execute commands on a device.
 
+.. _mass_commands:
+
+Mass Commands
+-------------
+
+Mass commands run the same command on many devices at once, for example to
+reboot all the devices of a organization, as shown in the GIF below:
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/mass-command-tutorial/mass_command_demo.gif
+    :target: https://github.com/openwisp/openwisp-controller/tree/docs/docs/mass-command-tutorial/mass_command_demo.gif
+    :alt: Sending a mass command
+
+Sending a Mass Command
+~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open *Network Operations* > *Run Mass command*.
+2. Choose the command, a **label** to recognize it later, and the
+   **targets**: organization, device group and location. Combining targets
+   narrows the selection.
+3. Review the matched devices, uncheck any you want to leave out, and
+   click **Execute**.
+
+Superusers can leave every target empty to run the command on all the
+devices, as shown in the GIF below:
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/mass-command-tutorial/mass_command_superuser.gif
+    :target: https://github.com/openwisp/openwisp-controller/tree/docs/docs/mass-command-tutorial/mass_command_superuser.gif
+    :alt: Running a mass command on all devices as a superuser
+
+Other users must choose at least one target and can only use the commands
+enabled for their organization (see
+:ref:`openwisp_controller_organization_enabled_commands`).
+
+From the Device List
+~~~~~~~~~~~~~~~~~~~~
+
+A mass command can also be started from the device list, as shown in the
+GIF below:
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/mass-command-tutorial/mass_command_action.gif
+    :target: https://github.com/openwisp/openwisp-controller/tree/docs/docs/mass-command-tutorial/mass_command_action.gif
+    :alt: Sending a mass command to selected devices
+
+Select the devices, choose *Execute mass command* from the actions
+dropdown and click **Go**. Then choose the command and review the devices
+as described above. The selected devices must belong to the same
+organization.
+
+Following the Results
+~~~~~~~~~~~~~~~~~~~~~
+
+After executing, the mass command page shows the status and output of each
+device, updated in real time, as shown in the GIF below:
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/mass-command-tutorial/mass_command_results.gif
+    :target: https://github.com/openwisp/openwisp-controller/tree/docs/docs/mass-command-tutorial/mass_command_results.gif
+    :alt: Following the results of a mass command
+
+- Devices which cannot run the command, for example because they have no
+  access credentials, are marked as *skipped* together with the reason.
+- Past mass commands are listed in *Network Operations* > *Mass commands*.
+- Commands sent by a mass command also appear in the **Recent Commands**
+  of each device, with a link back to the mass command.
+
+REST API
+~~~~~~~~
+
+Mass commands can also be sent and followed through the :ref:`Batch
+Command API <controller_batch_command_api>`.
+
 .. _defining_new_menu_options:
 
 Defining New Options in the Commands Menu