RUNTIME DOWNLOADS
Install the ozguard extension and run your encrypted product
ozguard is the small native PHP extension that runs OZP1-encrypted applications on your server. Pick the build that matches your PHP version below, verify the checksum, add two lines to php.ini — done.
Paste this link into an AI assistant like ChatGPT or Claude to explain this page.
https://onionzero.com/llms/runtime.txt
1 · Find the right build for your server
Three quick commands on the target server tell you exactly which cell of the matrix to download.
PHP version
Run php -v and note the major.minor version (for example 8.3). The matrix below has one row per version from PHP 8.0 to 8.5.
terminalphp -vThread safety (NTS or TS)
If the line says "Thread Safety => enabled", download a TS build; if it says "disabled", download an NTS build. The one-liner prints it directly.
terminalphp -i | grep "Thread Safety" # or simply: php -r "echo PHP_ZTS ? 'TS (ZTS)' : 'NTS', PHP_EOL;"Architecture must be x64
ozguard is published for 64-bit (x64) PHP only. The one-liner must print x64; 32-bit (x86) PHP is not supported.
terminalphp -r "echo PHP_INT_SIZE === 8 ? 'x64' : 'x86', PHP_EOL;"
2 · Download the matching build
All builds are served from the OnionZero API with a published SHA-256 checksum. Compare the checksum after download — never run a file that does not match.
Windows builds exist for both NTS and TS PHP 8.0–8.5; Linux builds exist for both NTS and TS (ZTS) PHP 8.1–8.5 — pick the flavour that matches your PHP (php -i → “Thread Safety”).
Legacy download endpoints
The original single-build endpoints stay online for existing integrations. They serve the same files as the PHP 8.3 NTS rows above.
432ca164321420…92aa979bee2921…3 · Install and enable
Two steps: drop the file into the PHP extension directory, then reference it from php.ini. The vendor public key is embedded in the extension at build time — no key line is needed.
Windows (AppServ, IIS, Apache)
Copy the DLL
Place the downloaded ozguard.dll into the PHP extension directory (for example C:\AppServ\php8\ext\).
Edit php.ini
Reference the DLL with a full path. The vendor public key is already embedded in the extension — oz_request_file() and the activation flows work without any key setting.
php.ini; php.ini — ozguard extension (customer server) extension = "C:\AppServ\php8\ext\ozguard.dll" ; The vendor public key is embedded in the extension (build time) — ; no php.ini key setting is required. ; Optional: application identity shown in the vendor panel ozguard.app_name = "my-application" ozguard.app_version = "2.1.0"Restart the web server
Restart Apache/IIS (or the AppServ services) so the module is loaded.
Linux (PHP-FPM / Apache)
Copy the .so into the extension directory
php-config reports the correct directory for your build.
terminalsudo cp ozguard.so "$(php-config --extension-dir)/"Enable the module
Debian/Ubuntu layout (mods-available + phpenmod); on other distros add the extension line to php.ini instead. No key setting — the vendor public key is embedded in the .so.
terminal# Debian/Ubuntu: echo 'extension = ozguard.so' | sudo tee /etc/php/8.3/mods-available/ozguard.ini sudo phpenmod ozguardRestart PHP
Restart FPM (or Apache) so the extension is loaded by the web SAPI.
terminalsudo systemctl restart php8.3-fpm # or: sudo systemctl restart apache2
4 · Verify the installation
Two checks: the file itself (checksum) and the loaded module list.
Compare the checksum
The printed digest must match the SHA-256 of your matrix cell exactly. If it does not, delete the file and download it again.
certutil -hashfile C:\AppServ\php8\ext\ozguard.dll SHA256sha256sum "$(php-config --extension-dir)/ozguard.so"The module must be listed
php -m | findstr ozguardphp -m | grep ozguard- php -m prints ozguard → the extension is loaded by the CLI.
- phpinfo() shows an ozguard section → the web SAPI loads it too (remember: web and CLI may read different php.ini files).
- The OZP1 key fingerprint line on the phpinfo page must match the fingerprint in your vendor delivery.
Troubleshooting
PHP Startup: ozguard: Unable to initialize module — “these options need to match”
Classic NTS/TS mix-up. The message ends with two build IDs such as “Module compiled with build ID=API20230831,NTS,VS16” vs “PHP compiled with …,TS,VS16”. Your PHP is thread-safe but you downloaded the NTS build (or vice versa). Go back to step 1, confirm with php -i | grep "Thread Safety", and download the other flavor of the same PHP version.
Warning: PHP Startup: ozguard: Unable to initialize module — different API numbers (e.g. API20220829 vs API20230831)
The module was built for another PHP version: the first number is the module’s PHP API (8.2 → 20220829), the second is your server’s (8.3 → 20230831). Download the row that matches php -v exactly; extensions do not load across minor versions.
Unable to load dynamic library ‘ozguard’ / ‘ozguard.so’ — No such file or directory
PHP cannot find the file where php.ini points. Check extension_dir with php --ini and php -i | grep extension_dir, prefer the mods-available + phpenmod layout on Debian/Ubuntu, and use a full absolute path on Windows.
The SHA-256 checksum does not match after download
Delete the file immediately and download it again over HTTPS. Do not load a module whose checksum differs from the matrix — it was corrupted or tampered with in transit.
php -m lists ozguard, but the application still reports the extension as missing
CLI and web SAPI (FPM/Apache/IIS) often use different php.ini files and the web server has not been restarted yet. Restart FPM/Apache, then confirm on a phpinfo() page that the ozguard section appears for the web SAPI.
Missing a build or stuck at a step?
Tell us your php -v output and operating system — we ship additional builds on request and help with the setup.