API Call to set instant Maintenance mode (#13237)

* API Call to set instance Maintenance mode

* .

* remove unused code

* update query

* Use recent code

* remove accidental line return

* fix duration in success string

* style fix

* Try to fix bad code merge

Co-authored-by: Tony Murray <murraytony@gmail.com>

doc/API/Devices.md

@@ -1103,6 +1103,32 @@ Output:
 }
 ```
 
+### `maintenance_device`
+
+Set a device into maintenance mode.
+
+Route: `/api/v0/devices/:hostname/maintenance`
+
+Input (JSON):
+
+- notes: Some description for the Maintenance
+- duration: Duration of Maintenance in format H:m
+
+Example:
+
+```curl
+curl -X POST -d '{"notes":"A 2 hour Maintenance triggered via API","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "message": "Device localhost.localdomain (57) moved into maintenance mode for 2:00 h"
+}
+```
+
 ### `add_device`
 
 Add a new device.

includes/html/api_functions.inc.php

@@ -22,6 +22,7 @@ use App\Models\PortGroup;
 use App\Models\PortsFdb;
 use App\Models\Sensor;
 use App\Models\ServiceTemplate;
+use App\Models\UserPref;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Routing\Router;
 use Illuminate\Support\Arr;
@@ -455,6 +456,48 @@ function del_device(Illuminate\Http\Request $request)
     return api_success([$device], 'devices', $response);
 }
 
+function maintenance_device(Illuminate\Http\Request $request)
+{
+    if (empty($request->json())) {
+        return api_error(400, 'No information has been provided to set this device into maintenance');
+    }
+
+    // This will add a device using the data passed encoded with json
+    $hostname = $request->route('hostname');
+
+    // use hostname as device_id if it's all digits
+    $device = ctype_digit($hostname) ? DeviceCache::get($hostname) : DeviceCache::getByHostname($hostname);
+
+    if (! $device) {
+        return api_error(404, "Device $hostname does not exist");
+    }
+
+    $notes = $request->json('notes');
+    $alert_schedule = new \App\Models\AlertSchedule([
+        'title' => $device->displayName(),
+        'notes' => $notes,
+        'recurring' => 0,
+        'start' => date('Y-m-d H:i:s'),
+    ]);
+
+    $duration = $request->json('duration');
+    if (Str::contains($duration, ':')) {
+        [$duration_hour, $duration_min] = explode(':', $duration);
+        $alert_schedule->end = \Carbon\Carbon::now()
+            ->addHours($duration_hour)->addMinutes($duration_min)
+            ->format('Y-m-d H:i:00');
+    }
+
+    $device->alertSchedules()->save($alert_schedule);
+
+    if ($notes && UserPref::getPref(Auth::user(), 'add_schedule_note_to_device')) {
+        $device->notes .= (empty($device->notes) ? '' : PHP_EOL) . date('Y-m-d H:i') . ' Alerts delayed: ' . $notes;
+        $device->save();
+    }
+
+    return api_success_noresult(201, "Device {$device->hostname} ({$device->device_id}) moved into maintenance mode" . ($duration ? " for {$duration}h" : ''));
+}
+
 function device_availability(Illuminate\Http\Request $request)
 {
     // return availability per device

routes/api.php

@@ -63,6 +63,7 @@ Route::group(['prefix' => 'v0', 'namespace' => '\App\Api\Controllers'], function
             Route::post('{hostname}/components/{type}', 'LegacyApiController@add_components')->name('add_components');
             Route::put('{hostname}/components', 'LegacyApiController@edit_components')->name('edit_components');
             Route::delete('{hostname}/components/{component}', 'LegacyApiController@delete_components')->name('delete_components');
+            Route::post('{hostname}/maintenance', 'LegacyApiController@maintenance_device')->name('maintenance_device');
         });
 
         Route::post('bills', 'LegacyApiController@create_edit_bill')->name('create_bill');