Skip to content

Commit ab21a52

Browse files
jaredhendrickson13jaredhendrickson13
authored
Merge pull request #78 from jaredhendrickson13/service_ntp_endpoint
NTP Service endpoints
2 parents 5166401 + d1711e7 commit ab21a52

10 files changed

Lines changed: 827 additions & 0 deletions

‎docs/documentation.json‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7404,6 +7404,105 @@
74047404
{
74057405
"name": "NTPD",
74067406
"item": [
7407+
{
7408+
"name": "TIME_SERVER",
7409+
"item": [
7410+
{
7411+
"name": "Create NTPd Time Server",
7412+
"request": {
7413+
"method": "POST",
7414+
"header": [],
7415+
"body": {
7416+
"mode": "raw",
7417+
"raw": "{\n \"timeserver\": \"ntp.pool.org\", \n \"ispool\": true, \n \"prefer\": true, \n \"noselect\": false\n}",
7418+
"options": {
7419+
"raw": {
7420+
"language": "json"
7421+
}
7422+
}
7423+
},
7424+
"url": {
7425+
"raw": "https://{{$hostname}}/api/v1/services/ntpd/time_server?timeserver=string&ispool=boolean&noselect=boolean&prefer=boolean",
7426+
"protocol": "https",
7427+
"host": [
7428+
"{{$hostname}}"
7429+
],
7430+
"path": [
7431+
"api",
7432+
"v1",
7433+
"services",
7434+
"ntpd",
7435+
"time_server"
7436+
],
7437+
"query": [
7438+
{
7439+
"key": "timeserver",
7440+
"value": "string",
7441+
"description": "Specify the IP or hostname of the NTP time server to add."
7442+
},
7443+
{
7444+
"key": "ispool",
7445+
"value": "boolean",
7446+
"description": "Specify whether or not this time server represents an NTP server pool or a single NTP server. "
7447+
},
7448+
{
7449+
"key": "noselect",
7450+
"value": "boolean",
7451+
"description": "Enable or disable this NTP time server from selection. If `true`, the time server will be eligible for selection. If `false, the NTP server will remain In the configuration but not used."
7452+
},
7453+
{
7454+
"key": "prefer",
7455+
"value": "boolean",
7456+
"description": "Enable or disable this NTP time server as a preferred NTP time server. If `true`, this time server will take preference over other time servers."
7457+
}
7458+
]
7459+
},
7460+
"description": "Add a new NTP time server to the NTPd configuration.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-services-ntpd`]"
7461+
},
7462+
"response": []
7463+
},
7464+
{
7465+
"name": "Delete NTPd Time Server",
7466+
"request": {
7467+
"method": "DELETE",
7468+
"header": [],
7469+
"body": {
7470+
"mode": "raw",
7471+
"raw": "{\n \"timeserver\": \"ntp.pool.org\"\n}",
7472+
"options": {
7473+
"raw": {
7474+
"language": "json"
7475+
}
7476+
}
7477+
},
7478+
"url": {
7479+
"raw": "https://{{$hostname}}/api/v1/services/ntpd/time_server?timeserver=string",
7480+
"protocol": "https",
7481+
"host": [
7482+
"{{$hostname}}"
7483+
],
7484+
"path": [
7485+
"api",
7486+
"v1",
7487+
"services",
7488+
"ntpd",
7489+
"time_server"
7490+
],
7491+
"query": [
7492+
{
7493+
"key": "timeserver",
7494+
"value": "string",
7495+
"description": "Specify the IP or hostname of the NTP time server to delete. If more than one time server exists with this value, only the first match will be deleted. In the case that all time servers were deleted, the default time server `pool.ntp.org` will be written."
7496+
}
7497+
]
7498+
},
7499+
"description": "Delete an existing NTP time server from the NTPd configuration.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-services-ntpd`]"
7500+
},
7501+
"response": []
7502+
}
7503+
],
7504+
"description": "API endpoints that create, read, update and delete NTPd configuration."
7505+
},
74077506
{
74087507
"name": "Start NTPd Service",
74097508
"request": {
@@ -7436,6 +7535,123 @@
74367535
},
74377536
"response": []
74387537
},
7538+
{
7539+
"name": "Read NTPd Service",
7540+
"protocolProfileBehavior": {
7541+
"disableBodyPruning": true
7542+
},
7543+
"request": {
7544+
"method": "GET",
7545+
"header": [],
7546+
"body": {
7547+
"mode": "raw",
7548+
"raw": "{\n \n}",
7549+
"options": {
7550+
"raw": {
7551+
"language": "json"
7552+
}
7553+
}
7554+
},
7555+
"url": {
7556+
"raw": "https://{{$hostname}}/api/v1/services/ntpd",
7557+
"protocol": "https",
7558+
"host": [
7559+
"{{$hostname}}"
7560+
],
7561+
"path": [
7562+
"api",
7563+
"v1",
7564+
"services",
7565+
"ntpd"
7566+
]
7567+
},
7568+
"description": "Read the ntpd service configuration.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-services-ntpd`]"
7569+
},
7570+
"response": []
7571+
},
7572+
{
7573+
"name": "Update NTPd Service",
7574+
"request": {
7575+
"method": "PUT",
7576+
"header": [],
7577+
"body": {
7578+
"mode": "raw",
7579+
"raw": "{\n \"interface\": [\"WAN\", \"lan\", \"lo0\"],\n \"orphan\": 15,\n \"logpeer\": true,\n \"logsys\": true,\n \"clockstats\": true,\n \"loopstats\": false,\n \"peerstats\": true,\n \"statsgraph\": true,\n \"timeservers\": [\n {\"timeserver\": \"ntp.pool.org\", \"ispool\": true, \"prefer\": true, \"noselect\": false}\n ]\n }",
7580+
"options": {
7581+
"raw": {
7582+
"language": "json"
7583+
}
7584+
}
7585+
},
7586+
"url": {
7587+
"raw": "https://{{$hostname}}/api/v1/services/ntpd?interface=array&time_servers=array&orphan=integer&leapsec=string&statsgraph=boolean&logpeer=boolean&logsys=boolean&clockstats=boolean&loopstats=boolean&peerstats=boolean",
7588+
"protocol": "https",
7589+
"host": [
7590+
"{{$hostname}}"
7591+
],
7592+
"path": [
7593+
"api",
7594+
"v1",
7595+
"services",
7596+
"ntpd"
7597+
],
7598+
"query": [
7599+
{
7600+
"key": "interface",
7601+
"value": "array",
7602+
"description": "Update the Interfaces NTPd will listen on. This must be an array of strings. You may specify either the physical Interface ID, the pfSense Interface ID or the descriptive Interface name. To match any Interface, simply pass In an empty array. e.g. `[\"wan\", \"em1\", \"lo0\", \"LAN\"]` (optional)"
7603+
},
7604+
{
7605+
"key": "time_servers",
7606+
"value": "array",
7607+
"description": "Update the time servers used by the system. This must be an array of objects. Each object may use the parameters available In the /api/v1/services/ntpd/time_server endpoint. To revert to the default timeserver, you may pass In an empty array. Specifying this field will overwrite any existing time servers. To simply add or remove time servers, use the /api/v1/services/ntpd/time_server endpoint as it Is less taxing on the system. e.g. `[{\"timeserver\": \"pool.ntp.org\", \"ispool\": true\", \"prefer\": true, \"noselect\": false}]` (optional)"
7608+
},
7609+
{
7610+
"key": "orphan",
7611+
"value": "integer",
7612+
"description": "Update the orphan mode value. This must be a value between `1` and `15`. Orphan mode allows the system clock to be used when no other clocks are available. The number here specifies the stratum reported during orphan mode and should normally be set to a number high enough to insure that any other servers available to clients are preferred over this server. (optional)"
7613+
},
7614+
{
7615+
"key": "leapsec",
7616+
"value": "string",
7617+
"description": "Update the leap seconds configuration. This should be the contents of the leap seconds file received from the IERS. (optional)"
7618+
},
7619+
{
7620+
"key": "statsgraph",
7621+
"value": "boolean",
7622+
"description": "Enable or disable RRD graphs of NTP metrics. (optional)"
7623+
},
7624+
{
7625+
"key": "logpeer",
7626+
"value": "boolean",
7627+
"description": "Enable or disable the logging of peer messages. (optional)"
7628+
},
7629+
{
7630+
"key": "logsys",
7631+
"value": "boolean",
7632+
"description": "Enable or disable the logging of system messages. (optional)"
7633+
},
7634+
{
7635+
"key": "clockstats",
7636+
"value": "boolean",
7637+
"description": "Enable or disable the logging of reference clock statistics. (optional)"
7638+
},
7639+
{
7640+
"key": "loopstats",
7641+
"value": "boolean",
7642+
"description": "Enable or disable the logging of clock discipline statistics. (optional)"
7643+
},
7644+
{
7645+
"key": "peerstats",
7646+
"value": "boolean",
7647+
"description": "Enable or disable the logging of NTP peer statistics. (optional)"
7648+
}
7649+
]
7650+
},
7651+
"description": "Update the ntpd service configuration.<br><br>\n\n_Requires at least one of the following privileges:_ [`page-all`, `page-services-ntpd`]"
7652+
},
7653+
"response": []
7654+
},
74397655
{
74407656
"name": "Restart NTPd Service",
74417657
"request": {

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
// Copyright 2021 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 APIServicesNTPd extends APIEndpoint {
19+
public function __construct() {
20+
$this->url = "/api/v1/services/ntpd";
21+
}
22+
23+
protected function get() {
24+
return (new APIServicesNTPdRead())->call();
25+
}
26+
27+
protected function put() {
28+
return (new APIServicesNTPdUpdate())->call();
29+
}
30+
}

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
// Copyright 2021 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 APIServicesNTPdTimeServer extends APIEndpoint {
19+
public function __construct() {
20+
$this->url = "/api/v1/services/ntpd/time_server";
21+
}
22+
23+
protected function post() {
24+
return (new APIServicesNTPdTimeServerCreate())->call();
25+
}
26+
27+
protected function delete() {
28+
return (new APIServicesNTPdTimeServerDelete())->call();
29+
}
30+
}

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,42 @@ function get($id, $data=[], $all=false) {
520520
"return" => $id,
521521
"message" => "DHCPd static mapping ID does not exist"
522522
],
523+
2046 => [
524+
"status" => "bad request",
525+
"code" => 400,
526+
"return" => $id,
527+
"message" => "NTPd orphan value must be between 1 and 15"
528+
],
529+
2047 => [
530+
"status" => "bad request",
531+
"code" => 400,
532+
"return" => $id,
533+
"message" => "Unknown NTPd interface specified"
534+
],
535+
2048 => [
536+
"status" => "bad request",
537+
"code" => 400,
538+
"return" => $id,
539+
"message" => "NTPd timeserver value is required"
540+
],
541+
2049 => [
542+
"status" => "bad request",
543+
"code" => 400,
544+
"return" => $id,
545+
"message" => "NTPd timeserver must be valid IP address or hostname"
546+
],
547+
2050 => [
548+
"status" => "bad request",
549+
"code" => 400,
550+
"return" => $id,
551+
"message" => "Maximum limit of 10 NTPd timeservers exceeded"
552+
],
553+
2051 => [
554+
"status" => "bad request",
555+
"code" => 400,
556+
"return" => $id,
557+
"message" => "NTPd timeserver does not exist"
558+
],
523559

524560
// 3000-3999 reserved for /interfaces API calls
525561
3000 => [
@@ -1744,6 +1780,7 @@ function get($id, $data=[], $all=false) {
17441780
"return" => $id,
17451781
"message" => "Authentication server name already in use"
17461782
],
1783+
17471784
//6000-6999 reserved for /routing API calls
17481785
6000 => [
17491786
"status" => "bad request",

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
// Copyright 2021 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 APIServicesNTPdRead extends APIModel {
21+
# Create our method constructor
22+
public function __construct() {
23+
parent::__construct();
24+
$this->privileges = ["page-all", "page-services-ntpd"];
25+
}
26+
27+
public function action() {
28+
# Return the current NTP configuration if it exists, otherwise return empty array
29+
if (isset($this->config["ntpd"])) {
30+
$data = $this->config["ntpd"];
31+
$data["timeservers"] = explode(" ", $this->config["system"]["timeservers"]);
32+
return APIResponse\get(0, $data);
33+
} else {
34+
return APIResponse\get(0, []);
35+
}
36+
}
37+
}

0 commit comments

Comments
 (0)