Skip to content

Commit 5bb9e23

Browse files
author
Jared Hendrickson
committed
Created endpoint for system status to pull system metrics such as cpu, mem, disk usage, created unit test for system status endpoint, updated docs
1 parent c65fa98 commit 5bb9e23

7 files changed

Lines changed: 254 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -648,6 +648,10 @@ There is no limit to API calls at this time but is important to note that pfSens
648648
* [Read Firewall Status Log](#3-read-firewall-status-log)
649649
* [Read System Status Log](#4-read-system-status-log)
650650

651+
* [STATUS/SYSTEM](#statussystem)
652+
653+
* [Read System Status](#1-read-system-status)
654+
651655
* [SYSTEM/API](#systemapi)
652656

653657
* [Read System API Configuration](#1-read-system-api-configuration)
@@ -3583,6 +3587,38 @@ URL: https://{{$hostname}}/api/v1/status/log/system
35833587

35843588

35853589

3590+
## STATUS/SYSTEM
3591+
3592+
3593+
3594+
### 1. Read System Status
3595+
3596+
3597+
Read system status and metrics.<br><br>
3598+
3599+
_Requires at least one of the following privileges:_ [`page-all`, `page-dashboard-widgets`, `page-dashboard-all`]
3600+
3601+
3602+
***Endpoint:***
3603+
3604+
```bash
3605+
Method: GET
3606+
Type: RAW
3607+
URL: https://{{$hostname}}/api/v1/status/system
3608+
```
3609+
3610+
3611+
3612+
***Body:***
3613+
3614+
```js
3615+
{
3616+
3617+
}
3618+
```
3619+
3620+
3621+
35863622
## SYSTEM/API
35873623

35883624

‎docs/documentation.json‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4661,6 +4661,58 @@
46614661
"description": "API endpoints that read interface statuses and metrics.",
46624662
"protocolProfileBehavior": {},
46634663
"_postman_isSubFolder": true
4664+
},
4665+
{
4666+
"name": "SYSTEM",
4667+
"item": [
4668+
{
4669+
"name": "Read System Status",
4670+
"protocolProfileBehavior": {
4671+
"disableBodyPruning": true
4672+
},
4673+
"request": {
4674+
"auth": {
4675+
"type": "bearer",
4676+
"bearer": [
4677+
{
4678+
"key": "token",
4679+
"value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJwZlNlbnNlIiwiZXhwIjoxNTk4MDcwMTAzLCJuYmYiOjE1OTgwNjE3MDMsImRhdGEiOiJhZG1pbiJ9.hgvNu96Bvsehcq6ygTa9LPB8eymiLnxYu4V6J8_h0-o",
4680+
"type": "string"
4681+
}
4682+
]
4683+
},
4684+
"method": "GET",
4685+
"header": [],
4686+
"body": {
4687+
"mode": "raw",
4688+
"raw": "{\n \n}",
4689+
"options": {
4690+
"raw": {
4691+
"language": "json"
4692+
}
4693+
}
4694+
},
4695+
"url": {
4696+
"raw": "https://{{$hostname}}/api/v1/status/system",
4697+
"protocol": "https",
4698+
"host": [
4699+
"{{$hostname}}"
4700+
],
4701+
"path": [
4702+
"api",
4703+
"v1",
4704+
"status",
4705+
"system"
4706+
]
4707+
},
4708+
"description": "Read system status and metrics.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-dashboard-widgets`, `page-dashboard-all`]"
4709+
},
4710+
"response": []
4711+
}
4712+
],
4713+
"description": "API endpoints that read system statuses.",
4714+
"protocolProfileBehavior": {},
4715+
"_postman_isSubFolder": true
46644716
}
46654717
],
46664718
"description": "API endpoints that read and update system statuses.",

‎pfSense-pkg-API/files/etc/inc/api/endpoints/APIStatusSystem.inc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?php
2+
// Copyright 2020 Jared Hendrickson
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// http://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
16+
require_once("api/framework/APIEndpoint.inc");
17+
18+
class APIStatusSystem extends APIEndpoint {
19+
public function __construct() {
20+
$this->url = "/api/v1/status/system";
21+
}
22+
23+
protected function get() {
24+
return (new APIStatusSystemRead())->call();
25+
}
26+
}

‎pfSense-pkg-API/files/etc/inc/api/framework/APITools.inc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1007,4 +1007,16 @@ function delete_static_route($id) {
10071007
}
10081008

10091009
unset($targets);
1010+
}
1011+
1012+
# Converts an integer-of-100 percent to a decimal percentage
1013+
function float_percent($value) {
1014+
# Only return converted value if it is numeric
1015+
if (is_numeric($value)) {
1016+
# Add a leading 0 if number is single digit
1017+
if (floatval($value) > 0 and floatval($value) < 10) {
1018+
$value = "0" . strval($value);
1019+
}
1020+
return floatval("0." . $value);
1021+
}
10101022
}

‎pfSense-pkg-API/files/etc/inc/api/models/APIStatusSystemRead.inc‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
<?php
2+
// Copyright 2020 Jared Hendrickson
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// http://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
16+
require_once("api/framework/APIModel.inc");
17+
require_once("api/framework/APIResponse.inc");
18+
19+
20+
class APIStatusSystemRead extends APIModel {
21+
# Create our method constructor
22+
public function __construct() {
23+
parent::__construct();
24+
$this->privileges = ["page-all", "page-dashboard-widgets", "page-dashboard-all"];
25+
}
26+
27+
public function action() {
28+
return APIResponse\get(0, $this->__get_metrics());
29+
}
30+
31+
private function __get_metrics() {
32+
include_once("includes/functions.inc.php");
33+
# Pre-return definitions
34+
foreach(get_mounted_filesystems() as $fs) {
35+
if ($fs["mountpoint"] === "/") {
36+
$disk_usage = APITools\float_percent($fs["percent_used"]);
37+
}
38+
}
39+
40+
# Place each gathered metric into our return array
41+
$sys_info = [
42+
"system_platform" => system_identify_specific_platform()["descr"],
43+
"system_serial" => system_get_serial(),
44+
"system_netgate_id" => system_get_uniqueid(),
45+
"bios_vendor" => $this->__get_bios_info()["bios_vendor"],
46+
"bios_version" => $this->__get_bios_info()["bios_version"],
47+
"bios_date" => $this->__get_bios_info()["bios_date"],
48+
"cpu_model" => get_single_sysctl("hw.model"),
49+
"mds_mitigation" => get_single_sysctl('hw.mds_disable_state'),
50+
"mbuf_usage" => $this->__get_mbuf_usage(),
51+
"temp_c" => $this->__get_temp(),
52+
"temp_f" => $this->__get_temp(false),
53+
"load_avg" => $this->__get_load_avg(),
54+
"mem_usage" => (!is_null(mem_usage())) ? APITools\float_percent(mem_usage()) : null,
55+
"swap_usage" => (!is_null(swap_usage())) ? APITools\float_percent(swap_usage()) : null,
56+
"disk_usage" => $disk_usage
57+
];
58+
return $sys_info;
59+
}
60+
61+
# Gathers our MBUF usage and returns either a float percentage or null if not calculable
62+
private function __get_mbuf_usage() {
63+
$mbufs_text = null;
64+
$mbuf_usage = null;
65+
get_mbuf($mbufs_text, $mbuf_usage);
66+
return (isset($mbuf_usage)) ? APITools\float_percent($mbuf_usage) : null;
67+
}
68+
69+
# Gets the current CPU temperatures in either Fº or Cº, return null if no temperature could be found
70+
private function __get_temp($celsius=true) {
71+
if ($celsius) {
72+
return (!empty(get_temp())) ? get_temp() : null;
73+
} else {
74+
return (!empty(get_temp())) ? get_temp() * 1.8 + 32 : null;
75+
}
76+
}
77+
78+
# Gets the current CPU load averages and formats them into an array of float percentages
79+
private function __get_load_avg() {
80+
foreach (explode(", ", get_load_average()) as $avg) {
81+
$load_avg[] = floatval($avg);
82+
}
83+
return $load_avg;
84+
}
85+
86+
# Gathers our BIOS information into a single dictionary
87+
private function __get_bios_info() {
88+
$bios_info = [
89+
"bios_vendor" => shell_exec('/bin/kenv -q smbios.bios.vendor 2>/dev/null'),
90+
"bios_version" => shell_exec('/bin/kenv -q smbios.bios.version 2>/dev/null'),
91+
"bios_date" => shell_exec('/bin/kenv -q smbios.bios.reldate 2>/dev/null'),
92+
];
93+
94+
# Remove newlines
95+
foreach ($bios_info as $key=>$value) {$bios_info[$key] = str_replace("\n", "", $value);}
96+
return $bios_info;
97+
}
98+
99+
}

0 commit comments

Comments
 (0)