Building the Mako Server with BAS

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.

Build Guide Roadmap

TaskWhere to Start
Use Mako Server without compiling itDownload a precompiled version from makoserver.net.
Build Mako Server from BASUse the make directory and its platform scripts, or include the required source files directly in your IDE or build system.
Support more concurrent connectionsChoose a socket dispatcher: epoll for Linux, poll for QNX.
Use a PSA Crypto providerFollow Building Mako with PSA Crypto for the Makefile and Visual Studio settings, startup, and provisioning.
Build quickly on Linux with common optional modulesUse the Ansible build script.
Customize Lua resourcesBuild or provide mako.zip. Keep the embedded ZIP as a fallback unless your deployment always ships an external mako.zip.
Prepare a hardened buildReview the extension hooks, signed ZIP support, SharkTrustX settings, and TPM configuration.

Compiling the Mako Server C Code

How to Compile the Mako Server C Code

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.

Choose a Socket Dispatcher

The socket dispatcher lets Mako manage browser, device, and service connections. Choose the dispatcher for your operating system when building the server:

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.

Source Files

FileRequiredPurpose
src/MakoMain.cYes Mako Server startup code. It creates the configurable standalone server using BAS.c.
src/MakoPosixMain.cPOSIX 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.cYes The Barracuda App Server library. See ../../amalgamation/README.txt for details.
src/SendError.cOptional 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.cOptional 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.cOptional Lua SQLite Lua bindings.
../../xrc/sql/luasql.cOptional Lua SQLite Lua bindings.
../../xrc/sql/sqlite3.cOptional 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.

Resource Files

The Mako Server requires Lua and web resource files. The make directory includes two scripts for assembling these resources:

ScriptOutputPurpose
BuildInternalZipobj/LspZip.cBuilds the minimum internal fallback resources and converts them to C. You can exclude this file by compiling with MAKO_ENABLE_EMBEDDED_ZIP_FALLBACK=0.
BuildMakoZipmako.zipBuilds 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.

SQL Databases

The default build includes SQLite. You can also compile the Mako Server without built-in SQL support or with ITTIA database bindings.

MacroResult
MAKO_SQL_BACKEND=0No embedded database.
MAKO_SQL_BACKEND=1Embedded SQLite.
MAKO_SQL_BACKEND=2ITTIA database Lua bindings. You must also embed the ITTIA database.

Command-line Compile Example

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:

export INC="-I ../../inc/ -I../../inc/arch/Posix -I../../inc/arch/NET/Posix"

Set the required C compiler flags:

export CFLAGS="-pthread -O3 -Os -DNDEBUG -DMAKO -DMAKO_ENABLE_EMBEDDED_ZIP_FALLBACK=0 -DMAKO_SQL_BACKEND=0"

Add the following to CFLAGS when compiling for a 64-bit processor:

-DBA_ARCH_64BIT=1 -Wno-int-to-pointer-cast -Wno-pointer-to-int-cast

Compile and link:

gcc -o mako $CFLAGS $INC ../../amalgamation/BAS.c src/MakoMain.c src/MakoPosixMain.c src/SendError.c -lm

Using the Makefile

See make/README.txt for details.

Build Mako with PSA Crypto

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.

1. Configure the Build

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.

2. Initialize Your Provider

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.

3. Rebuild the Executable and Resources

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.

4. Verify and Retain the Keys

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.

Additional Configuration and Security Settings

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.

FilePurpose
MakoExt1.chEmpty extension point for custom macros, helper functions, or supporting logic.
MakoExt2.chPlatform 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.chExtension 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.chWhite-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.

SharkTrustX, SharkCA, and tokengen.c

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.

Trusted Platform Module (TPM)

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.