Skip to content
OnionZero
STATUS: 100% AIR-GAPPED · CORE INTACT Technical Briefing
OnionZero
STATUS: 100% AIR-GAPPED · CORE INTACT
Technical Briefing
TR EN

SETUP GUIDE

Install the ozguard extension on your server

To run your OZP1-encrypted application, the ozguard extension only needs to be registered with PHP. It takes about 5 minutes and is done once.

This guide targets your own server (VPS, dedicated or on-prem). Shared hosting plans cannot load custom PHP extensions, so code encryption does not run there — see our FAQ for details. FAQ

COMPATIBILITY MATRIX

One build per PHP flavor

Native extensions bind to an exact PHP minor version and thread-safety. Match your php -v output to a row; every published cell is a download on the runtime page.

PHP version Windows · NTS Windows · TS (ZTS) Linux · NTS Linux · TS (ZTS)
PHP 8.0 Available Available Not available Not available
PHP 8.1 Available Available Available Available
PHP 8.2 Available Available Available Available
PHP 8.3 Available Available Available Available
PHP 8.4 Available Available Available Available
PHP 8.5 Available Available Available Available

Windows: NTS and TS builds for PHP 8.0–8.5, x64. Linux: NTS and TS (ZTS) builds for PHP 8.1–8.5, x64 — distro/FPM PHP is NTS in practice, while mod_php and custom builds need TS. 32-bit PHP is not supported. Every cell is a download with a SHA-256 checksum in the runtime matrix.

Where the binaries live

ozguard.dll / ozguard.so files are downloaded per PHP flavor from the runtime matrix — each row carries its SHA-256 checksum.

Get your build

The five-minute console

Full command sequences per platform — copy a tab, paste, restart PHP, done. Guided walkthroughs for each OS follow below.

Linux · bash
sudo cp ozguard.so "$(php -i | awk -F'=> ' '/extension_dir/{print $2}')/"
echo "extension = ozguard.so" | sudo tee /etc/php/8.3/mods-available/ozguard.ini
sudo phpenmod ozguard && sudo systemctl restart php8.3-fpm
Windows · PowerShell
Copy-Item .\ozguard.dll "C:\AppServ\php8\ext\"
Add-Content "C:\AppServ\php8\php.ini" "`nextension = \"C:\AppServ\php8\ext\ozguard.dll\""
httpd -k restart   # Apache — or: iisreset
php.ini
; php.ini — enable the OnionZero runtime
extension = ozguard.so

; Vendor public key is embedded in the extension — nothing else to set
Dockerfile
FROM php:8.3-fpm
COPY ozguard.so /usr/local/lib/php/extensions/
RUN echo "extension = ozguard.so" \
  > /usr/local/etc/php/conf.d/ozguard.ini

Installation on Windows

  1. Copy the extension file

    Copy ozguard.dll into your PHP extensions directory; on AppServ installs this is usually C:\AppServ\php8\ext\.

  2. Add the php.ini lines

    Open the php.ini file in use (php --ini shows the correct file) and add these lines:

    php.ini
    extension = "C:\AppServ\php8\ext\ozguard.dll"

; The vendor public key is embedded in the extension — no key setting needed.

  3. Restart the web server

    Run "httpd -k restart" for Apache, "iisreset" for IIS, or restart the PHP-FPM Windows service if you use one. The CLI (command line) needs no restart.

  4. Verify the installation

    Run the following command; the output must contain an ozguard line:

    command prompt
    php -m | findstr ozguard

A phpinfo() page shows an ozguard section; the key fingerprint there must match the fingerprint delivered with your product package.

Installation on Linux

  1. Copy the extension file

    Find the PHP extension directory and copy ozguard.so into it:

    terminal
    php -i | grep extension_dir
sudo cp ozguard.so /usr/lib/php/20230831/

  2. Add the php.ini lines

    Add the following lines to the php.ini used by PHP-FPM:

    php.ini
    extension = ozguard.so

; The vendor public key is embedded in the extension — no key setting needed.

  3. Alternative: enable with phpenmod

    On Debian/Ubuntu-based systems you can also use a dedicated ini file:

    terminal
    echo 'extension = ozguard.so' | sudo tee /etc/php/8.3/mods-available/ozguard.ini
sudo phpenmod ozguard

  4. Restart PHP-FPM

    If you run Apache with mod_php, restart the apache2 service instead.

    terminal
    sudo systemctl restart php8.3-fpm

  5. Verify the installation

    The following command must show an ozguard line:

    terminal
    php -m | grep ozguard

Verification

You can confirm a successful setup in two ways:

  • The ozguard module appearing in the php -m output shows that PHP has loaded the extension.
  • The key fingerprint in the ozguard section of a phpinfo() page must match the value delivered with your package — this proves the extension and your encrypted files belong together.

Troubleshooting

"Unable to load dynamic library" error

The extension file does not match your PHP version or thread-safety mode. Download the cell that matches your php -v output from the runtime matrix (Windows 8.0–8.5 NTS/TS, Linux 8.1–8.5 NTS/TS, x64); 32-bit PHP is not supported.

No ozguard in the php -m output

Make sure you edited the correct php.ini file (php --ini shows the path) and that you restarted PHP-FPM / the web server.

Stops working after a PHP upgrade

PHP extensions are specific to a minor release (e.g. 8.3 → 8.4). Request an extension build for the new version from us before upgrading.

Container fleets: Bake ozguard into the image once; every container wakes up with the vault armed. The Dockerfile tab in the console above is the whole recipe.

Need help with the setup?

Our team can guide you for your specific server environment — just write to us.

Contact Us