Skip to content

Commit 4a25258

Browse files
Created pfsense-api command line tool to aid with configuration backup, restorating, updates, uninstallation and reverting version, added persistent config mode to keep API config even after update
1 parent 4455966 commit 4a25258

11 files changed

Lines changed: 223 additions & 55 deletions

File tree

README.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,17 @@ pkg add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/downlo
2626

2727
To uninstall pfSense API, run the following command:<br>
2828
```
29-
pkg delete pfSense-pkg-API
29+
pfsense-api delete
3030
```
3131

32-
To update pfSense API to latest version, run the following command:
32+
To update pfSense API to latest stable version, run the following command:
3333
```
34-
pkg delete pfSense-pkg-API && pkg add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.4-pkg-API.txz && /etc/rc.restart_webgui
34+
pfsense-api update
35+
```
36+
37+
To revert to a previous version of pfSense API (e.g. v1.0.2), run the following command:
38+
```
39+
pfsense-api revert v1.0.2
3540
```
3641

3742
### Notes:
@@ -40,6 +45,7 @@ pkg delete pfSense-pkg-API && pkg add https://github.com/jaredhendrickson13/pfse
4045
- If you do not have shell access to pfSense, you can still install via the webConfigurator by navigating to
4146
'Diagnostics > Command Prompt' and enter the commands there
4247
- When updating pfSense, **_you must reinstall pfSense API afterwards_**. Unfortunately, pfSense removes all existing packages and only reinstalls packages found within pfSense's package repositories. Since pfSense API is not an official package in pfSense's repositories, it does not get reinstalled automatically.
48+
- The `pfsense-api` command line tool was introduced in v1.1.0. Refer to the corresponding documentation for earlier releases.
4349

4450

4551
# UI Settings & Documentation
@@ -169,7 +175,7 @@ curl -s -H "Content-Type: application/x-www-form-urlencoded" -X GET "https://pfs
169175

170176

171177
# Error Codes
172-
A full list of error codes can be found by navigating to /api/v1/system/api/errors/ after installation. This will return
178+
A full list of error codes can be found by navigating to /api/v1/system/api/error after installation. This will return
173179
JSON data containing each error code and their corresponding error message. No authentication is required to view the
174180
error code library. This also makes API integration with third-party software easy as the API error codes and messages
175181
are always just an HTTP call away!

docs/documentation.json

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

pfSense-pkg-API/files/pkg-deinstall.in

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ if [ "${2}" != "POST-DEINSTALL" ]; then
55
fi
66

77
/usr/local/bin/php -f /etc/rc.packages %%PORTNAME%% ${2}
8+
/bin/rm /usr/local/bin/pfsense-api
89
/bin/mv /etc/inc/system.original.inc /etc/inc/system.inc

pfSense-pkg-API/files/pkg-install.in

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,8 @@ fi
55
/usr/local/bin/php -f /etc/rc.packages %%PORTNAME%% ${2}
66
/bin/cp /etc/inc/system.inc /etc/inc/system.original.inc
77
/bin/cp /etc/inc/api/framework/overrides/system.inc /etc/inc/system.inc
8+
/bin/chmod +x /usr/local/share/pfSense-pkg-API/manage.php
9+
/bin/ln -s /usr/local/share/pfSense-pkg-API/manage.php /usr/local/bin/pfsense-api
810
/usr/local/bin/php -f /usr/local/share/pfSense-pkg-API/manage.php buildendpoints
11+
/usr/local/bin/php -f /usr/local/share/pfSense-pkg-API/manage.php restore
12+

pfSense-pkg-API/files/usr/local/pkg/api.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,18 @@
66
<![CDATA[
77
/**
88
* API
9-
* - A Full API for pfSense
9+
* - The missing REST API package for pfSense
1010
*
1111
* Copyright 2020 Jared Hendrickson
1212
*/
1313
]]>
1414
</copyright>
15-
<description>A REST API for pfSense</description>
15+
<description>The missing REST API package for pfSense</description>
1616
<name>API</name>
1717
<title>System: API</title>
1818
<menu>
1919
<name>API</name>
20-
<tooltiptext>A REST API for pfSense.</tooltiptext>
20+
<tooltiptext>The missing REST API package for pfSense</tooltiptext>
2121
<section>System</section>
2222
<url>/api/</url>
2323
</menu>

pfSense-pkg-API/files/usr/local/share/pfSense-pkg-API/info.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,15 @@
33
<package>
44
<name>API</name>
55
<internal_name>api</internal_name>
6-
<descr><![CDATA[A full API for pfSense]]></descr>
6+
<descr><![CDATA[The missing REST API package for pfSense]]></descr>
77
<website>https://github.com/jaredhendrickson13/pfsense-api</website>
88
<category>System</category>
99
<version>%%PKGVERSION%%</version>
1010
<configurationfile>api.xml</configurationfile>
1111
<maintainer>jaredhendrickson13@gmail.com</maintainer>
1212
<conf>
1313
<enable></enable>
14+
<persist></persist>
1415
<allowed_interfaces>any</allowed_interfaces>
1516
<authmode>local</authmode>
1617
<content_type>json</content_type>

pfSense-pkg-API/files/usr/local/share/pfSense-pkg-API/manage.php

Lines changed: 126 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@
1313
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1414
// See the License for the specific language governing permissions and
1515
// limitations under the License.
16+
require_once("api/framework/APITools.inc");
1617

17-
# MAKEENDPOINTS COMMAND
18-
if ($argv[1] === "buildendpoints") {
18+
function build_endpoints() {
1919
# Import each endpoint class
2020
foreach(glob("/etc/inc/api/endpoints/*.inc") as $file) {
2121
# Import classes files and create object
@@ -39,8 +39,131 @@
3939
if (!is_null($endpoint_obj->url) and is_file("/usr/local/www".$endpoint_obj->url."/index.php")) {
4040
echo "Builing ".$endpoint_class." endpoint at URL \"".$endpoint_obj->url."\"... done.".PHP_EOL;
4141
} else {
42-
echo "Failed to build ".$endpoint_class." endpoint at URL \"".$endpoint_obj->url."\"".PHP_EOL;
42+
echo "Builing ".$endpoint_class." endpoint at URL \"".$endpoint_obj->url."\"... failed.".PHP_EOL;
4343
exit(1);
4444
}
4545
}
4646
}
47+
48+
function backup() {
49+
# Local Variables
50+
$api_conf = APITools\get_api_config()[1];
51+
$backup_api_conf = json_encode($api_conf);
52+
file_put_contents("/usr/local/share/pfSense-pkg-API/backup.json", $backup_api_conf);
53+
echo "Backing up API configuration... done.".PHP_EOL;
54+
}
55+
56+
function restore() {
57+
global $config;
58+
59+
# Local Variables
60+
$api_conf = APITools\get_api_config();
61+
$backup_api_conf_json = file_get_contents("/usr/local/share/pfSense-pkg-API/backup.json");
62+
$backup_api_conf = json_decode($backup_api_conf_json, true);;
63+
64+
# Restore our API configuration if the backup exists
65+
if (!empty($backup_api_conf_json)) {
66+
# Only restore the config if it has changed
67+
if ($api_conf[1] !== $backup_api_conf) {
68+
$config["installedpackages"]["package"][$api_conf[0]]["conf"] = $backup_api_conf;
69+
write_config("Synchronized persistent API configuration");
70+
echo "Restoring API configuration... done.".PHP_EOL;
71+
} else {
72+
echo "Restoring API configuration... no changes found.".PHP_EOL;
73+
}
74+
} else {
75+
echo "Restoring API configuration... no configuration found.".PHP_EOL;
76+
}
77+
}
78+
79+
function update() {
80+
echo shell_exec("/usr/sbin/pkg delete -y pfSense-pkg-API");
81+
echo shell_exec("/usr/sbin/pkg add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.4-pkg-API.txz");
82+
echo shell_exec("/etc/rc.restart_webgui");
83+
}
84+
85+
function revert($version) {
86+
# Local variables
87+
$pf_version = substr(file_get_contents("/etc/version"), 0, 3);
88+
$url = "https://github.com/jaredhendrickson13/pfsense-api/releases/download/".urlencode($version)."/pfSense-".$pf_version."-pkg-API.txz";
89+
echo "Locating pfSense-pkg-API-".$version." at ".$url."... ";
90+
91+
# Check our URL for the existence of this version
92+
$headers = @get_headers($url);
93+
94+
# If this release exists, remove the existing package and install the requested one. Otherwise return error
95+
if($headers && strpos($headers[0], '302')) {
96+
echo "done.".PHP_EOL;
97+
echo shell_exec("/usr/sbin/pkg delete -y pfSense-pkg-API");
98+
echo shell_exec("/usr/sbin/pkg add ".$url);
99+
echo shell_exec("/etc/rc.restart_webgui");
100+
} else {
101+
echo "no package found.".PHP_EOL;
102+
exit(1);
103+
}
104+
}
105+
106+
function delete() {
107+
echo shell_exec("/usr/sbin/pkg delete -y pfSense-pkg-API");
108+
echo shell_exec("/etc/rc.restart_webgui");
109+
}
110+
111+
function version() {
112+
echo shell_exec("/usr/sbin/pkg info pfSense-pkg-API");
113+
}
114+
115+
function help() {
116+
echo "pfsense-api - CLI tool for pfSense API management".PHP_EOL;
117+
echo "Copyright - ".date("Y")."© - Jared Hendrickson".PHP_EOL;
118+
echo "SYNTAX:".PHP_EOL;
119+
echo " pfsense-api <command> <args>".PHP_EOL;
120+
echo "COMMANDS:".PHP_EOL;
121+
echo " version : Display the current package version and build information".PHP_EOL;
122+
echo " help : Display the help page (this page)".PHP_EOL;
123+
echo " buildendpoints : Build all API endpoints included in this package".PHP_EOL;
124+
echo " update : Update package to the latest stable version available".PHP_EOL;
125+
echo " revert : Revert package to a specified version".PHP_EOL;
126+
echo " delete : Delete package from this system".PHP_EOL;
127+
echo " backup : Create a backup of the API configuration".PHP_EOL;
128+
echo " restore : Restore the API configuration from the latest backup".PHP_EOL;
129+
echo PHP_EOL;
130+
}
131+
132+
# MAKEENDPOINTS COMMAND
133+
if (in_array($argv[1], ["buildendpoints"])) {
134+
build_endpoints();
135+
}
136+
# BACKUP COMMAND
137+
elseif (in_array($argv[1], ["backup"])) {
138+
backup();
139+
}
140+
# RESTORE COMMAND
141+
elseif (in_array($argv[1], ["restore"])) {
142+
restore();
143+
}
144+
# UPDATE COMMAND
145+
elseif (in_array($argv[1], ["update"])) {
146+
update();
147+
}
148+
# REVERT COMMAND
149+
elseif (in_array($argv[1], ["revert"])) {
150+
revert($argv[2]);
151+
}
152+
# DELETE COMMAND
153+
elseif (in_array($argv[1], ["delete"])) {
154+
delete();
155+
}
156+
# VERSION COMMAND
157+
elseif (in_array($argv[1], ["version"])) {
158+
version();
159+
}
160+
# HELP COMMAND
161+
elseif (in_array($argv[1], ["help", null])) {
162+
help();
163+
164+
}
165+
# UNKNOWN COMMAND/DEFAULT
166+
else {
167+
echo "Unknown command".PHP_EOL.PHP_EOL;
168+
help();
169+
}

0 commit comments

Comments
 (0)