pfSense® Actions

This is a Docker-based image to be deployed on a local server that allows you to run quick actions remotely without logging into your pfSense® system.

This controller allows you to run simple actions such as Wake-on-LAN and reloading firewall filters. This controller prioritizes security in its design and does not allow modifying or exporting any configurations.

To use this controller, here are three simple steps you need to follow:

1. Deploy the controller using the instructions below.
2. Verify your deployment after the Docker runs successfully.
3. Implement this controller using your scripts!

Instructions

Run this controller using a Docker run command. Before deployment, ensure that you have SSH configured on your firewall, then replace the environment variables to run the container.

docker run \
    -d \
    -e "API_KEY=" \
    -e "PORT=" \
    -e "PFSENSE_SSH_IP=192.168.1.1" \
    -e "PFSENSE_SSH_PORT=22" \
    -e "PFSENSE_USERNAME=admin" \
    -e "PFSENSE_PASSWORD=pfsense" \
    -e "PFSENSE_PRIVATE_KEY=" \
    -p 9898:9898 \
    --name pfsense-actions \
    mrjackyliang/pfsense-actions:latest

Alternatively, a docker-compose.yml is provided to you, with a sample below. Simply paste the configuration shown below and replace the environment variables:

services:
  pfsense-actions:
    image: "mrjackyliang/pfsense-actions:latest"
    environment:
      - "API_KEY="
      - "PORT="
      - "PFSENSE_SSH_IP=192.168.1.1"
      - "PFSENSE_SSH_PORT=22"
      - "PFSENSE_USERNAME=admin"
      - "PFSENSE_PASSWORD=pfsense"
      - "PFSENSE_PRIVATE_KEY="
    ports:
      - "9898:9898"

Environment Variables

Variable	Description	Required	Default
API_KEY	An API key used to access pfSense® Actions	false	Randomly generates a UUID on every start-up
PORT	The HTTP port used to access pfSense® Actions	false	9898
PFSENSE_SSH_IP	IP address of your pfSense® firewall used to initiate an SSH connection	true
PFSENSE_SSH_PORT	SSH port of your pfSense® firewall used to initiate an SSH connection	true
PFSENSE_USERNAME	Username to login to your pfSense® firewall	true
PFSENSE_PASSWORD	Password to login to your pfSense® firewall	true
PFSENSE_PRIVATE_KEY	Contents of the private key to login to your pfSense® firewall	true

Available Endpoints

Endpoint	Description	Method	Instructions
reload-filter	Reload the filters on your pfSense® firewall	GET	Reload Filter Endpoint
update-dyndns	Update the Dynamic DNS settings on your pfSense® firewall	GET	Update Dynamic DNS Endpoint
wol	Send a Wake-on-LAN request to a connected device	POST	Wake-on-LAN Endpoint
wol-check	Send a Wake-on-LAN check request to a connected device	POST	Wake-on-LAN Check Endpoint

Authorizing Your Requests

When accessing the controller, ensure that you have the Authorization header properly set to the API_KEY you specified during image creation. For example:

GET http://localhost:9898
Authorization: Bearer [YOUR_API_KEY]

Note: To protect against data leaks, the server only replies with HTTP response codes.

Note 2: If you do not specify an API_KEY during build, an API_KEY will be provided for you and will randomize on every container restart.

Setting Up Secure Shell

The controller authenticates itself through the Secure Shell (SSH). If you have not enabled Secure Shell, follow the instructions below:

1. Login to the pfSense web interface.
2. Under the System dropdown, click Advanced.
3. Scroll down to the Secure Shell section.
4. Check the Enable Secure Shell checkbox.
5. Click the Save button at the bottom of the page.

Note: Ensure that the user you are logging in from has the User - System: Shell account access privilege.

Note 2: If you wish to use a private key, paste the contents of the key into the PFSENSE_PRIVATE_KEY directly and do not include the path of the file.

Using the Endpoints

This section describes how to interact with the available API endpoints for managing your pfSense® firewall.

Reload Filter Endpoint:

GET http://localhost:9898/reload-filter
Authorization: Bearer [YOUR_API_KEY]

Update Dynamic DNS Endpoint:

GET http://localhost:9898/update-dyndns
Authorization: Bearer [YOUR_API_KEY]

Wake-on-LAN Endpoint:

POST http://localhost:9898/wol
Authorization: Bearer [YOUR_API_KEY]
Content-Type: application/json

{
  "broadcastAddress": "[YOUR_BROADCAST_IP_ADDRESS]",
  "macAddress": "[YOUR_MAC_ADDRESS]"
}

Wake-on-LAN Check Endpoint:

POST http://localhost:9898/wol-check
Authorization: Bearer [YOUR_API_KEY]
Content-Type: application/json

{
  "ipAddress": "[YOUR_IP_ADDRESS]",
}

Retrieving the Broadcast IP Address

In order to send a Wake-on-LAN request, a broadcast address is required since magic packets cannot be sent across subnets. Follow the instructions below:

1. Login to the pfSense web interface.
2. Under the Interfaces dropdown, click on the interface where the device belongs to.
3. On the address bar, look for the if= parameter and copy the value. The interface value should look something like igb1, opt1, or lan.
4. Copy the PHP Code shown below and replace [YOUR_INTERFACE_ID] with your interface value.
5. Run the code under Diagnostics > Command Prompt > Execute PHP Commands section.
6. Retrieve the calculated IP address above in the PHP Response section.

PHP Code:

$interface = '[YOUR_INTERFACE_ID]';

echo gen_subnet_max(get_interface_ip($interface), get_interface_subnet($interface));

Credits and Appreciation

If you find value in the ongoing development of this controller and wish to express your appreciation, you have the option to become my supporter on GitHub Sponsors!