core Documentation

1. Project Overview & Quickstart (opnsense/core) Copy Chapter

File: README.md Copy Chapter

OPNsense GUI and system management

The OPNsense project invites developers to start contributing to
the code base. For your own purposes or – even better – to join us in
creating the best open source firewall available.

The build process has been designed to make it easy for anyone to
build and write code. The main outline of the new codebase is
available at:

https://docs.opnsense.org/development/architecture.html

Our aim is to gradually evolve to a new codebase instead of using a
big bang approach into something new.

Build tools

To create working software like OPNsense you need the sources and the
tools to build it. The build tools for OPNsense are freely available.

Notes on how to build OPNsense can be found in the tools repository:

https://github.com/opnsense/tools

Contribute

You can contribute to the project in many ways, e.g. testing
functionality, sending in bug reports or creating pull requests
directly via GitHub. Any help is always very welcome!

You can learn more about contributing on CONTRIBUTING.md.

License

OPNsense is and will always be available under the 2-Clause BSD license:

https://opensource.org/licenses/BSD-2-Clause

Every contribution made to the project must be licensed under the
same conditions in order to keep OPNsense truly free and accessible
for everybody.

Makefile targets

The repository offers a couple of targets that either tie into
tools.git build processes or are aimed at fast development.

make package Copy Chapter

A package of the current state of the repository can be created using
this target. It may require several packages to be installed. The
target will try to assist in case of failure, e.g. when a missing file
needs to be fetched from an external location.

Several OPTIONS exist to customise the package, e.g.:

• CORE_DEPENDS: a list of required dependencies for the package
• CORE_DEPENDS_ARCH: a list of special -required packages
• CORE_ORIGIN: sets a FreeBSD compatible package/ports origin
• CORE_COMMENT: a short description of the package
• CORE_MAINTAINER: email of the package maintainer
• CORE_WWW: web url of the package
• CORE_NAME: sets a package name

Options are passed in the following form:

# make package CORE_NAME=my_new_name

In general, options are either set to sane defaults or automatically
detected at runtime.

make update Copy Chapter

Update will pull the latest commits from the current branch from the
upstream repository.

make upgrade Copy Chapter

Upgrade will run the package build and replace the currently installed
package in the system.

make collect Copy Chapter

Fetch changes from the running system for all known files.

make lint Copy Chapter

Run several syntax checks on the repository. This is recommended
before issuing a pull request on GitHub.

make style Copy Chapter

Run the PSR12 and PEP8 style checks on MVC PHP code and Python,
respectively.

For easier development you may want to use an OPNsense VM and install
the os-debug plugin that will offer the necessary tools.

make sweep Copy Chapter

Run several automatic sanitizers on the code base.

File: contrib/parallel-lint/README.md Copy Chapter

PHP Parallel Lint

This application checks syntax of PHP files in parallel.
It can output in plain text, colored text, json and checksyntax formats.
Additionally blame can be used to show commits that introduced the breakage.

Running parallel jobs in PHP is inspired by Nette framework tests.

The application is officially supported for use with PHP 5.3 to 8.1.

Table of contents Copy Chapter

1. Installation
2. Example output
3. History
4. Command line options
5. Recommended excludes for Symfony framework
6. Excluding files from a scan based on the PHP version used
7. How to upgrade

Installation Copy Chapter

Install with composer as development dependency:

composer require --dev php-parallel-lint/php-parallel-lint

Alternatively you can install as a standalone composer project:

composer create-project php-parallel-lint/php-parallel-lint /path/to/folder/php-parallel-lint
/path/to/folder/php-parallel-lint/parallel-lint # running tool

For colored output, install the suggested package php-parallel-lint/php-console-highlighter:

composer require --dev php-parallel-lint/php-console-highlighter

Since v1.3.0, a PHAR file is also made available for each release.
This PHAR file is published as an asset for each release and can be found on the Releases page.

Example output Copy Chapter

History Copy Chapter

This project was originally created by @JakubOnderka and released as
jakub-onderka/php-parallel-lint.

Since then, Jakub has moved on to other interests and as of January 2020, the
second most active maintainer @grogy has taken over maintenance of the project
and given the project - and related dependencies - a new home in the PHP
Parallel Lint organisation.

It is strongly recommended for existing users of the (unmaintained)
jakub-onderka/php-parallel-lint package to switch their dependency to
php-parallel-lint/php-parallel-lint, see How to upgrade below.

Command line options Copy Chapter

• -p Specify PHP-CGI executable to run (default: 'php').
• -s, --short Set short_open_tag to On (default: Off).
• -a, --asp Set asp_tags to On (default: Off).
• -e <ext> Check only files with selected extensions separated by comma. (default: php,php3,php4,php5,phtml,phpt)
• -j <num> Run jobs in parallel (default: 10).
• --exclude Exclude a file or directory. If you want exclude multiple items, use multiple exclude parameters.
• --colors Enable colors in console output. (disables auto detection of color support)
• --no-colors Disable colors in console output.
• --no-progress Disable progress in console output.
• --checkstyle Output results as Checkstyle XML.
• --json Output results as JSON string (requires PHP 5.4).
• --gitlab Output results for the GitLab Code Quality Widget (requires PHP 5.4), see more in Code Quality documentation..
• --blame Try to show git blame for row with error.
• --git <git> Path to Git executable to show blame message (default: 'git').
• --stdin Load files and folder to test from standard input.
• --ignore-fails Ignore failed tests.
• --show-deprecated Show deprecations (default: Off).
• --syntax-error-callback File with syntax error callback for ability to modify error, see more in example.
• -h, --help Print this help.
• -V, --version Display the application version

Recommended excludes for Symfony framework Copy Chapter

To run from the command line:

vendor/bin/parallel-lint --exclude .git --exclude app --exclude vendor .

Excluding files from a scan based on the PHP version used Copy Chapter

Sometimes a particular file in a project may not comply with the project-wide minimum PHP version, like a file which is conditionally included in the project and contains PHP syntax which needs a higher PHP version to run.

This can make it complicated to run Parallel Lint in a CI context, as the excludes used in the command would have to be adjusted based on the PHP version on which the scan is being run.

PHP Parallel Lint offers a straight-forward way around this, as files can define their own minimum PHP version like so:

<?php // lint >= 7.4

// Code which contains PHP 7.4 syntax.

With this comment in place, the file will be automatically skipped when PHP Parallel Lint is run on a PHP version lower than PHP 7.4.

Note: The // lint >= 7.4 comment has to be only the first line of the file and must directly follow the PHP open tag.

How to upgrade Copy Chapter

Are you using jakub-onderka/php-parallel-lint package? You can switch to php-parallel-lint/php-parallel-lint using:

composer remove --dev jakub-onderka/php-parallel-lint
composer require --dev php-parallel-lint/php-parallel-lint

File: src/opnsense/mvc/app/models/OPNsense/Firewall/DynamicAliases/README.md Copy Chapter

DynamicAliases

This namespace may contain simple classes which generate aliases that should be merged automatically in Firewall/Aliases.
Each class should have a collect() method returning a named array with alias registration info.

An easy example of the expected result can be found in ../static_aliases/core.json

** Note: make sure actions are "light weight" to prevent excessive api execution times.

2. Official Technical Reference & Guides (opnsense/docs) Copy Chapter

OPNsense documentation

Welcome to the OPNsense documentation & wiki.
The purpose of this project is to provide OPNsense users with quality documentation.

Contribute Copy Chapter

You can contribute to the project in many ways, e.g. testing
functionality, sending in bug reports or creating pull requests
directly via GitHub. Any help is always very welcome!

License Copy Chapter

OPNsense documentation is available under the 2-Clause BSD license:

https://opensource.org/licenses/BSD-2-Clause

Every contribution made to the project must be licensed under the
same conditions in order to keep OPNsense truly free and accessible
for everybody.

Some pictures are licensed under the Creative Commons Zero (CC0) license:

https://creativecommons.org/publicdomain/zero/1.0/

Logos may be subject to additional copyrights, property
rights, trademarks etc. and may require the consent of a third party or the
license of these rights. Deciso B.V. does not represent or make any warranties
that it owns or licenses any of the mentioned, nor does it grant them.

Prepare build

On FreeBSD the following packages are required:

pkg install python py311-pip jpeg-turbo gmake

Install Sphinx, our default theme and contrib packages:

pip install -r requirements.txt --upgrade

Update API endpoints Copy Section

A script is provided to update the api endpoint documentation, this can be
executed using:

./collect_api_endpoints.py --repo core /path/to/core/repository
./collect_api_endpoints.py --repo plugins /path/to/plugins/repository

Generate HTML documents

gmake html

(gmake clean to flush)

Live preview of HTML documents

Use sphinx-autobuild to track source for changes and get a live preview served via http://localhost:8000.

pip install sphinx-autobuild

sphinx-autobuild source build/html

Publish BIOS ROM Images

BIOS ROM images are written to Deciso appliances using a FAT32 formatted (thumb) drive containing in its root directory
the combined contents of the source/hardware/files/BIOS_update_sources.zip file and the latest platform-specific
compressed BIOS ROM image. The BIOS_update_sources directory contains the EFI boot structure to trigger the
startup.nsh file when booting from the drive and kickstart the update using the LATEST.FD file.

The SHA256 hash of the BIOS_update.sources.zip file:

0cf1b042223482ea073a7a3599d6170be7c849ff8399936cf5a9db1ec5406dcf  BIOS_update_sources.zip

To create a publishable archive, use the provided make_bios.py script and give it the platform type, version number and
source .fd file:

./make_bios.py --platform <A10|A20|A30> --version <version> --source <.FD filename>

Example output:

2d5143f221fa120ef6d5c8799a90bd2c08e8238b3b9dd350327336d0605944a6 source/hardware/files/A10_v30_bios.tar.gz

A SHA256 hash of the resulting compressed archive is provided for integrity checking.