Preparing pfSense - RestAPI install
Full RestAPI documentation:
https://github.com/aml-one/pfSense-RestAPI
Installation (in pfSense host shell):
Login to pfSense with SSH, and type the following commands:
fetch https://github.com/aml-one/pfSense-RestAPI/raw/main/releases/restapi_latest.tar.xz
tar -xf restapi_latest.tar.xz
cd pfSense-pkg-RestAPI
./install.sh
cp /etc/restapi/credentials.sample.ini /etc/restapi/credentials.ini
- Need to configure the credentials for Hala Server
Open up the /etc/restapi/credentials.ini with vi in command line.
Or head to the pfSense web console in your webbrowser, log in,
and go to Diagnostic / Edit File, then place the /etc/restapi/credentials.ini in the "path to file to be edited" input field, and click the Load button.
At the bottom of the file create a new credential:
[<apikey_value>]
secret = <apisecret_value>
permit = config_*, rule_*, send_*
comment = <name or description of the credential>
<apikey_value> and <apisecret_value> may have alphanumeric chars ONLY!
<apikey_value> MUST start with the prefix REST
<apikey_value> MUST be >= 12 chars AND <= 40 chars in total length
<apisecret_value> MUST be >= 40 chars AND <= 128 chars in length
To make things easier consider using the following shell commands to generate valid values:
apikey_value
echo REST`head /dev/urandom | base64 -w0 | tr -d /+= | head -c 20`
apisecret_value
echo `head /dev/urandom | base64 -w0 | tr -d /+= | head -c 60`
Example:
[RESTexample01]
secret = abcdefghijklmnopqrstuvwxyz0123456789abcd
permit = config_*, rule_*, send_*
comment = example key RESTexample01 - hardcoded to be inoperative
After a successful install, you can see the credentials in the System / RestAPI section of the pfSense web console.
SERVER
(Requirement: .net 8 Desktop Runtime)
First need to setup .NET 8 Desktop Runtime then Hala on the server which will be responsible to request rule changes from pfSense host!
Download .NET 8 Desktop Runtime
- server has to have access to pfSense host. (be able to reach it)
- install the service:
Download Hala Server
(During installation, the installer will open up firewall port 13000 and setup a rule with netsh to start listening on that port)
(If you choose a different port for the app, then don't forget to open the port on firewall
and allow for listen on that port with the following cmd command:
netsh http add urlacl url=http://*:13000/ user=Everyone
You can set different user to tighten security eg.: user=DOMAIN\username)
Note: Based on time settings on pfSense host, change UTCTime=True or UTCTime=False in order to use UTC or local time
(If the authentication fails, try to change the UTCTime in Config.ini and restart the service)
Edit config file: (ProgramFiles\AmL\Hala - pfSense Auto Rule Changer\Config.ini)
[pfSense]
HostIP=<pfSense host IP>
UTCTime=<True|False>
[RestAPI]
Secret=<RestAPI Secret encoded in base64>
APIKey=<RestAPI API key encoded in base64>
[WebServer]
ListeningPort=<Port>
Logging=False
Note: the APIKey and Secret has to be encoded in base64 in the Server's config file.
For base64 encode you can use: https://www.base64encode.org/
After successful configuration, start the service with services.msc
(find it as: Hala - pfSense Auto Rule Changer)
For debug purposes, you can temporarily start the service in File Explorer like a normal application.
Note: The service installation folder has to be writable by the current user. Cause the service will store the Log file in the same folder, when the Debug is enabled in config file.
Important: Make sure the client side (Hala Server) clock is within 60 seconds of the pfSense host clock else the auth token values calculated by the client (Hala Server) will not be valid!
CLIENT
(Requirement: .net 8 Desktop Runtime)
- Install .NET 8 Desktop Runtime first
Download .NET 8 Desktop Runtime
- Install Hala Client
Download Hala Client
Edit config file: (ProgramFiles\AmL\Hala - Public IP Change Sender App\Config.ini)
[WebServer]
Debug=False
PostAddress=<Hala Server address:port - eg: http://IP:PORT/>
User=<Part or exact match of pfSense rule Description>
[Address]
PublicIP=1.1.1.1
Leave PublicIP at 1.1.1.1 or setup any random IP which doesn't match the client's current IP
You can start/stop the service with services.msc
(find it as: Hala - Public IP Change Sender App)