Skip to content

Scripts

Operational tasks — building, packaging, deploying, starting, stopping, status — are wrapped in shell scripts under scripts/. They are POSIX shell or Bash, and most are idempotent. The reference flows are: build locally; install on a target host; pack a release tarball; unpack and run on a fresh host.

Build

scripts/build.sh

Compiles the C++ sources via CMake. Behaviour:

  1. Ensures lib/, bin/, log/, and the cdr/{new,processed,error}/ directories exist.
  2. Detects the OS (Darwin vs Linux) and assembles the platform-specific list of required shared libraries (libACE, libACE_SSL, libprotobuf, libgrpc++, libgrpc, libmysqlcppconnx, libplutobook, plus several libabsl_* on macOS).
  3. For each required library, scans the system search paths and copies the matching .dylib/.so files into ./lib/. Each copied real file gets a sibling .sha256 checksum so subsequent builds can skip already-vendored copies.
  4. Optionally vendors the PHP grpc.so extension when present, so the bundled tarball can ship the same grpc.so the CRM frontend uses.
  5. If any required library could not be located, calls scripts/install.sh --deps-only to install dependencies, then re-checks.
  6. Runs cmake . and cmake --build . --target all -j $cores. On success, executes scripts/sync_crm_grpc.sh to publish the regenerated PHP gRPC stubs to the adjacent crm2.micro.bss repository.

Run from the repository root: ./scripts/build.sh.

scripts/build_ace.sh

Bootstrap script for ACE itself, used only when lib/libACE* is absent. It:

  1. Queries the GitHub API for the latest ACE_TAO release tag.
  2. Downloads the source tarball into a temporary directory.
  3. Generates a minimal config.h and platform_macros.GNU for the active OS.
  4. Builds with make ssl=1 -j$cores.
  5. With the install argument, runs make install INSTALL_PREFIX=/usr/local.

Usage: ./scripts/build_ace.sh Linux install or ./scripts/build_ace.sh macOS install.

Install

scripts/install.sh

A two-mode script:

  • install.sh install — copies a freshly built tree from the repository into $PREFIX (default /opt/microbss), splitting it into bin/, lib/, etc/ (config and SSL), var/invoices/, keys/, license/, and cdr/{new,processed,error}/.
  • install.sh (no args) or install.sh --deps-only — runs the dependency provisioning pipeline: detects OS, installs build prerequisites via Homebrew (macOS) or apt (Ubuntu/Debian), fetches Inja and plutobook from source if not present, downloads the latest MySQL Connector/C++ X DevAPI .deb packages on Linux, patches MySQL headers to dodge a name collision with gRPC's INTERNAL macro, then triggers build.sh and install.sh install.

The end-to-end flow on a clean Ubuntu 24.04 host is:

./scripts/install.sh                      # provision deps, build, install to /opt/microbss
mysql -u root -p < sql/install.sql        # load schema (manual step, called out at the end)

The script also deploys the adjacent crm2.micro.bss PHP frontend if it is cloned next to the server repository, including composer install --no-dev and an rsync into the configured HTDOCS (default /var/www/crm2).

Pack and Unpack

scripts/pack.sh

Creates a self-contained release tarball named microbss-dist-<OS>-<arch>.tar.gz. Refuses to run if bin/server or bin/licensing is missing. Stages a fresh directory tree with bin/, lib/, config/, html/, ssl/, certs/, invoices/, sql/, log/, scripts/, keys/, license/, copies the corresponding directories from the source tree, copies a curated subset of scripts (run.sh, status.sh, kill.sh, update_toml.sh, cdr_generator.sh, client.sh), tar -czf the staging directory, then deletes the staging copy. The result is a single archive ready for transfer to a target host.

scripts/unpack.sh

Counterpart to pack.sh. Usage: ./scripts/unpack.sh <archive.tar.gz> <target_dir>. Steps:

  1. Creates <target_dir>.
  2. Extracts the archive with --strip-components=1 so the tarball's top-level directory does not nest inside the target.
  3. Restores executable bits on run.sh and every binary in bin/.
  4. Tightens permissions on keys/ (700) and keys/* (600) — the license tooling private keys must not be world-readable.
  5. Calls scripts/update_toml.sh with the target directory so absolute paths in the bundled TOML files are rewritten to match the deployment.

The script ends with a startup hint:

cd <target_dir>
./run.sh all

Run, Stop, Status

scripts/run.sh

Starts one role (or every role) under nohup. Usage:

./run.sh all                  # start every role
./run.sh prepaid              # start one role and tail its log
./run.sh billing              # special case: starts billing1..billing4

For each role, it invokes nohup ./bin/server -i./config/<role>.toml > ./log/<role>.server.log 2>&1 &. The billing shortcut starts four processes, one per bill-cycle. The script truncates the existing logs before launching.

scripts/kill.sh

The structured stop path. Walks every running bin/server process via ps -eo pid,args, parses out which TOML each process was started with, and matches against the requested target. Sends SIGTERM, waits up to 5 seconds, then escalates to SIGKILL if needed.

./scripts/kill.sh all          # graceful stop all roles
./scripts/kill.sh prepaid      # stop only the prepaid role
./scripts/kill.sh billing      # stop billing1..billing4

The graceful path lets SignalHandler invoke CRMServer::shutdown() (5-second deadline for in-flight RPCs to drain), the thread pool shutdown, and the reactor's cancel_timer for each timer handler.

scripts/status.sh

Prints a one-line status per running role, mapping the TOML name to a friendly label. Useful as a smoke test after run.sh all:

PID        MODULE NAME
--------------------------------------------------------
12345      Prepaid Server
12346      Billing server for billcycle 1
12347      Billing server for billcycle 2
12348      Billing server for billcycle 3
12349      Billing server for billcycle 4
12350      CDR Loader
12351      Stats Server
12352      CRM Server
12353      Bill Formatter Server

Auxiliary

scripts/cdr_generator.sh

Wrapper around bin/cdr_generator. Loads config/cdr_generator.toml and writes synthetic CDR files into the configured new_cdr_path. Used to feed the loader during development and load testing.

scripts/client.sh

Launches bin/diameter_client against config/diameter_client.toml to drive synthetic CCR traffic at the prepaid server.

scripts/sync_crm_grpc.sh

Copies the freshly generated PHP gRPC stubs (produced by the CMake generate_php_proto target into build/generated/php/) into the adjacent crm2.micro.bss repository so the PHP frontend has matching client classes.

scripts/update_toml.sh

Rewrites absolute paths inside the config/*.toml files to match the deployment root. Invoked by install.sh and unpack.sh; not normally run by hand.

scripts/repo_reset.sh

Top-level cleanup helper used during development to reset build artefacts and logs.

Python helpers

scripts/fix_exceptions.py, scripts/parse_check.py, scripts/parse_db_methods.py, scripts/patch_methods.py, and scripts/test_db.py are development aids — not used at deploy time. They exist to refactor C++ exception handling, scan the database method surface, and exercise individual DB_layer methods in isolation. patch_install.py (in the repo root) is a related installer-patching helper.

Test helpers

scripts/run_lldb.sh and scripts/run_silent.sh are local-development entry points for debugging and headless runs. scripts/run_test.sh is a tiny shim used by the test infrastructure under Testing/.

Typical Operator Workflow

# On the build host
./scripts/build.sh
./scripts/pack.sh

# Transfer microbss-dist-Linux-x86_64.tar.gz to the deployment host

# On the deployment host
./scripts/unpack.sh microbss-dist-Linux-x86_64.tar.gz /opt/microbss
cd /opt/microbss
mysql -u <user> -p < sql/install.sql
./run.sh all
./scripts/status.sh

Stopping the platform: ./scripts/kill.sh all.