search

jaredhendrickson13 / pfsense-api

The missing REST API package for pfSense
https://pfrest.org/
Apache License 2.0
674 stars 103 forks source link

Update documentation to highlight two different packages #548

Closed HovKlan-DH closed 2 weeks ago

HovKlan-DH commented 3 weeks ago

For people not being too familiar with the install process or just tend to forget things, then ideally the install documentation could highlight that there are two different releases/packages. The error message given when installing the wrong package does not reveal the real problem but simply states:

An error occured while fetching package

Giving visibility on multiple packages can reduce filed issues here 😁

Adaption on documentation page could be to change it into something like this:

Installing the package

The pfSense REST API package is built just like any other pfSense package and can therefor be installed easily using pkg from the pfSense command line. Do note that there are two different packages, depending on your system:

pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.7.2-pkg-RESTAPI.pkg

If you are installing this on Netgate hardware then use this:

pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-24.03-pkg-RESTAPI.pkg

jaredhendrickson13 commented 3 weeks ago

There are a couple different things here:

First, the An error occured while fetching package is more likely to do with the pkg system not being up-to-date on the system, which is more problematic with pfSense Plus because the plus package repos are locked down more than the CE repos. Running pkg-static update is generally the fix for that, although that doesn't happen often. When trying to install a version that was not built for the running version of pfSense (for example, installing the 24.03 build on 2.7.2, you get this error:

$ pkg add https://github.com/jaredhendrickson13/pfsense-api/releases/download/v2.1.0/pfSense-24.03-pkg-RESTAPI.pkg
Fetching pfSense-24.03-pkg-RESTAPI.pkg: 100%  783 KiB 801.8kB/s    00:01
Installing pfSense-pkg-RESTAPI-2.1...
pkg: wrong architecture: FreeBSD:15:* instead of FreeBSD:14:amd64

Failed to install the following 1 package(s): https://github.com/jaredhendrickson13/pfsense-api/releases/download/v2.1.0/pfSense-24.03-pkg-RESTAPI.pkg

The only reason the package is built for specific versions of pfSense like it is currently is because the underlying versions of FreeBSD vary across releases. When CE and Plus are operating on the same FreeBSD version, it actually doesn't matter which package is used to install as the package's code is exactly the same across both.

Second, as for the documentation, this is the intent of the notation below the install command:

Screenshot 2024-08-31 at 8 22 55 AM

I can differentiate the commands between CE and Plus, but even then it won't be fully sufficient as there are times where the package is built for older versions of CE and Plus alongside the latest where the issue could still occur. I will definitely make this scenario more apparent though. Appreciate the suggestion!