This document explains how to build the Mako Server from the Barracuda App Server (BAS) source tree. The Mako Server is the ready-to-run Lua application server built on BAS for high-level operating systems such as Linux, Windows, macOS, QNX, and VxWorks.
Use this page when you are compiling, porting, or customizing the Mako Server C code. Use Using the Mako Server for command-line options,
mako.conf, application loading, modules, and runtime APIs. For downloads, tutorials, and product-level documentation, see makoserver.net.
| Task | Where to Start |
|---|---|
| Use Mako Server without compiling it | Download a precompiled version from makoserver.net. |
| Build Mako Server from BAS | Use the make directory and its platform scripts, or include the required source files directly in your IDE or build system. |
| Support more concurrent connections | Choose a socket dispatcher: epoll for Linux, poll for QNX. |
| Use a PSA Crypto provider | Follow Building Mako with PSA Crypto for the Makefile and Visual Studio settings, startup, and provisioning. |
| Build quickly on Linux with common optional modules | Use the Ansible build script. |
| Customize Lua resources | Build or provide mako.zip. Keep the embedded ZIP as a fallback unless your deployment always ships an external mako.zip. |
| Prepare a hardened build | Review the extension hooks, signed ZIP support, SharkTrustX settings, and TPM configuration. |
The make directory contains the generic makefile and several ready-to-use build scripts that call it. See make/README.txt for the platform-specific details.
As an alternative to the makefile, include the required source files directly in your build system or IDE.
Quick Linux build with extended features:
If you are targeting embedded Linux or want to quickly test Mako Server on Linux, consider using the provided Ansible build script. It uses the amalgamated BAS library and compiles Mako with a set of optional plugins.
The socket dispatcher lets Mako manage browser, device, and service connections. Choose the dispatcher for your operating system when building the server:
make/build.sh selects it automatically. When invoking make directly, use plat=posix BA_USE_EPOLL=1.plat=qnx. Poll allows connections beyond the generic select dispatcher's descriptor limit. Use BA_USE_POLL=0 if you need the generic dispatcher.plat=posix BA_USE_POLL=1 when you need more connections than the generic dispatcher allows.Use one dispatcher and its matching headers for the server and any libraries. Clean and rebuild all objects and prebuilt libraries when switching. See HTTP Engine and Sockets for capacity planning and Mako connection settings for runtime configuration.
| File | Required | Purpose |
|---|---|---|
src/MakoMain.c | Yes | Mako Server startup code. It creates the configurable standalone server using BAS.c. |
src/MakoPosixMain.c | POSIX command-line builds | Optional main() wrapper that calls runMako(). Omit this source when the application supplies its own entry point. Windows uses the sources in src/Windows. |
../../amalgamation/BAS.c | Yes | The Barracuda App Server library. See ../../amalgamation/README.txt for details. |
src/SendError.c | Optional | Traps errors and optionally reports the errors, including asserts, if enabled. You may use another error handler or remove the call in MakoMain.c. |
obj/LspZip.c | Optional | Internal fallback ZIP converted to a C array by bin2c and assembled by running BuildInternalZip. Exclude by compiling with MAKO_ENABLE_EMBEDDED_ZIP_FALLBACK=0. |
../../xrc/sql/ls_sqlite3.c | Optional | Lua SQLite Lua bindings. |
../../xrc/sql/luasql.c | Optional | Lua SQLite Lua bindings. |
../../xrc/sql/sqlite3.c | Optional | SQLite database. |
When compiling for Windows, include all C files in the src/Windows subdirectory. These files enable the server to be installed as a Windows service.
The Mako Server requires Lua and web resource files. The make directory includes two scripts for assembling these resources:
| Script | Output | Purpose |
|---|---|---|
BuildInternalZip | obj/LspZip.c | Builds the minimum internal fallback resources and converts them to C. You can exclude this file by compiling with MAKO_ENABLE_EMBEDDED_ZIP_FALLBACK=0. |
BuildMakoZip | mako.zip | Builds the external resource file used by the Mako Server at startup. This script requires a copy of the BAS-Resources repository in BAROOT/../BAS-Resources. |
In most deployments, ship the external mako.zip file with the Mako executable. It includes resources used by components such as the TraceLogger and the File Manager. The internal ZIP is only a fallback if mako.zip is not found. If the server is compiled without the internal ZIP and cannot mount mako.zip, startup fails.
The default build includes SQLite. You can also compile the Mako Server without built-in SQL support or with ITTIA database bindings.
| Macro | Result |
|---|---|
MAKO_SQL_BACKEND=0 | No embedded database. |
MAKO_SQL_BACKEND=1 | Embedded SQLite. |
MAKO_SQL_BACKEND=2 | ITTIA database Lua bindings. You must also embed the ITTIA database. |
The Mako Server can be compiled directly on the command line without using the makefile. The following example compiles the Mako Server for POSIX/Linux without SQLite and without the internal ZIP file (obj/LspZip.c).
Start by setting the include path:
Set the required C compiler flags:
Add the following to CFLAGS when compiling for a 64-bit processor:
Compile and link:
See make/README.txt for details.
PSA mode keeps the ba.tpm Lua API and uses your platform's cryptographic provider and key store. For a first Windows run, follow the Windows quick start. Its supplied project handles development provisioning automatically.
For your own target, first check the provider requirements and choose device-specific or shared data. The steps below use device-specific data, which needs no manual root provisioning. Hardware protection depends on your provider and selected key locations.
Makefile: in make/Makefile, leave usebalibs unset and retain the existing BA_ENABLE_TPM=1. Enable the optional UNIX PSA block, using your provider's real paths, and add the device-root definition:
# Enable PSA and automatic device-specific root creation. CFLAGS += $(MFT)SHARKSSL_PSA_CONSUMER=1 CFLAGS += $(MFT)BA_PSA_GLOBALKEY_USE_DEVICE_ROOT=1 CFLAGS += $(IFT)/path/to/provider/include BA_EXTLIBS += /path/to/provider/lib/libpsacrypto.a # Provider acceleration belongs in the provider's own build. SHARKSSL_ASM = off
Put the provider headers before other PSA headers and include its required system libraries. Add your platform initialization source to SOURCE and append its directory to VPATH after the existing assignment. For a Windows Makefile build, add provider libraries to the link command, which does not use BA_EXTLIBS. Remove manually enabled native assembly definitions if your build has them.
Visual Studio: open VcMake/mako-psa.vcxproj. Building this project also builds the simulator provider from C source for the selected platform and configuration; no separate provider build is required. For your own provider, set PsaTestSimulator=false, supply the provider properties, and add BA_PSA_GLOBALKEY_USE_DEVICE_ROOT=1 to its C/C++ preprocessor definitions. The project already selects PSA and disables native assembly. The alternative procedure for converting the original project is in How It Works.
BAS.c already includes the PSA binding and consumer adapters. Link the provider separately; do not compile those included files again. Keep Lua's default 64-bit integers, including in Win32 builds.
The TPM uses HKDF-SHA-512 by default. To select HKDF-SHA-256, set SHARKSSL_USE_SHA_512=0 in the Makefile, or MSBuild property SharkSslUseSha512=0 in the PSA project. The project forwards this setting to its simulator library; configure an external provider separately. Changing the hash requires root and encrypted-data migration.
Implement int makoInitPsa(void), declared in src/mako.h, and compile it into your host. Initialize entropy, hardware access, and persistent storage in the provider's required order, including a successful psa_crypto_init(). Return 0 on success or a nonzero error to stop startup.
Mako calls this hook after service/daemon setup, before cryptographic use, resource verification, and Lua creation. Keep the provider open across debugger restarts and make repeated calls safe. Use MakoExtM1.ch only for process prerequisites; move existing PSA initialization into makoInitPsa(). See the hook contract for ordering and lifetime details.
Mako registers and initializes the Lua TPM automatically. With the device-root setting above, it creates the root on first use and reuses it later. If you chose shared data instead, omit that definition and install the shared global root before starting Mako.
Clean and rebuild all objects. For example, run these commands from examples/MakoServer/make on Linux after completing steps 1 and 2:
# Compile all objects with the selected PSA settings. make plat=posix SHARKSSL_ASM=off clean make plat=posix SHARKSSL_ASM=off MAKONAME=mako-psa exe
Build a current mako.zip with make/BuildMakoZip.sh on Linux or make/BuildMakoZip.bat on Windows, running the script from the make directory. Place the archive beside the executable. The PSA Visual Studio project copies it automatically. No PSA selection flag is needed for Mako's resource builder.
Run the Lua signing example, then restart and check that it reuses the stored key. Keep the provider's key store, certificates, and ACME state across updates. Recover existing softTPM-encrypted data before switching, or plan a reset. Initialization errors stop startup. See How It Works for storage and recovery details.
The Mako Server is designed to allow customization and extension without requiring changes to MakoMain.c. Extension files are included at defined points in the startup code and let you add platform logic, product-specific Lua bindings, and security settings.
| File | Purpose |
|---|---|
MakoExt1.ch | Empty extension point for custom macros, helper functions, or supporting logic. |
MakoExt2.ch | Platform and security extension point. It can enforce signed ZIP validation, set a global ZIP password, and extend softTPM startup through makoOpenAUX(). PSA builds skip makoOpenAUX(); use MakoExtM2.ch for custom Lua bindings and makoInitPsa() for provider initialization. Search this file for BA_ENABLE_ZIP_SIGNATURE=1 and BA_ENABLE_ZIP_PASSWORD=1. See Signed and Encrypted ZIP Files. |
MakoExtM1.ch, MakoExtM2.ch, MakoExtM3.ch, MakoExtM4.ch | Extension points in runMako(). MakoExtM1.ch runs once per invocation, before service/daemon setup. The other hooks run for each Lua state, including debugger restarts. Use makoInitPsa() for PSA provider initialization. |
MakoWBC.ch | White-box cryptography logic used by the TPM key-derivation implementation. |
Note: When signed ZIP files are enabled, the Mako Server will only mount deployed ZIP applications. This means all ZIP files, including mako.zip, must be signed. If mako.zip is not signed or is signed with an incorrect signature, the following error will occur at server startup:
Mounting path/2/mako.zip Fatal error: cannot mount mako.zip.
The generated C file tokengen.c includes SharkTrustX settings for the demo portal local.makoserver.net. If you're using your own SharkTrustX or SharkCA portal, replace tokengen.c with the version generated by your portal and select the matching Automatic TLS Certificate configuration. To exclude this code, compile with the BA_ENABLE_SHARKTRUST=0 macro. Do not include tokengen.c in your build, as MakoMain.c includes it as a header file.
Mako generates its default self-signed TLS certificate using a named TPM key. The resource package no longer contains a shared default private key. Use a configured certificate or ACME for an identity trusted by clients. If no TPM is installed, Mako warns that default TLS is not enabled.
The standard Mako executable and matching mako.zip include the TPM integration. Keep it enabled and initialized for automatic TLS certificate management, which uses the TPM for ACME account keys and ECC certificate keys, including with SharkCA.
Standard builds use softTPM. For PSA, use the PSA build steps; the embedded-secret settings below apply only to softTPM. Detailed backend settings are in How It Works.
Mako softTPM Details and Required Configuration
The src/EncryptionKey.h file contains a binary random number of variable length the product designer (you) set. This number is consistent across all firmware copies and supplemented with additional per-device-specific entropy (DDUI). Instead of modifying EncryptionKey.h, you may create a new file called NewEncryptionKey.h and compile with MAKO_SOFTTPM_KEY_HEADER="NewEncryptionKey.h" (escape the quotes as required by your compiler command line).
The BA_ENABLE_SOFTTPM_KEY_MATERIAL=0 macro excludes this key-derivation implementation. A custom build using the standard automatic certificate setup must still provide and initialize a TPM implementation.
Device-Derived Unique Identifier (DDUI)
This softTPM implementation needs stable device-specific input, called a Device-Derived Unique Identifier (DDUI), for device-bound keys. Without it, devices sharing the same product secret generate identical private keys for a given name and options. A public identifier such as a MAC address distinguishes devices operationally but can be copied; it is not a secret or proof of hardware binding. See the softTPM security model.
The file PushUniqueKey.ch, included by MakoExt2.ch, provides a helper function, pushUniqueKey(), with platform-specific implementations for pushing the MAC address onto the Lua stack. If this code cannot derive a DDUI, it will print a warning message.
For best results, the DDUI should be derived from hardware-based uniqueness (e.g., CPU serial number, MAC address, or another hardware fingerprint). This guarantees that the identifier is both deterministic and device-specific.
The Embedded softTPM Lua Code
For security reasons, the Lua-based TPM implementation, which is loaded and initialized by the C code, is embedded in the Mako Server binary. The file MakoTPM.lua has been renamed to .config, zipped, converted to a C code, and included in the Mako Server as tpm.h. The file MakoMain.c includes this file and initializes the TPM during startup. The Lua TPM code calculates a pre-master secret based on the data provided by the C code. This pre-master secret forms the basis for generating multiple unique secrets, instrumental in creating TPM keys. These keys are not stored but are regenerated with each system restart, significantly reducing the risk of key leakage.
Suggested release compile time macros:
In addition to NDEBUG, the following settings are recommended to secure this TPM implementation: do not define BA_ENABLE_LUA_DEBUGGER=1, and compile with BA_ENABLE_LUA_DEBUG_LIBRARY=0 to disable the Lua debug API.