The Master Controller is the central management hub for an ESCTL installation. It manages the logic, security permissions, and data logging for all connected door controllers and temperature monitors.

Core Functions

  • Identity Management: Integrates with LDAP/Active Directory to manage user permissions and card serial numbers.
  • Access Logic: Determines real-time access rights based on groups, time of day, and door ID.
  • Data Logging: Centralized logging of all events (access granted, access denied, temperature readings) to a MySQL/MariaDB database.
  • API Access: Provides an interface for remote commands and configuration.

System Architecture

The Master Controller typically runs on a Linux-based server (or Raspberry Pi). It consists of several perl-based services:

  • esctl-node.pl: The main service communicating with hardware nodes.
  • ldap.pm: Handles integration with the identity provider.
  • functions.pm: Core utility logic.

Configuration

The system is configured via a central configuration file (typically config.pm). The available settings include:

General & Hardware Settings

  • $site_default_dooropentime (Default: 3): How many seconds to hold the door open by default.
  • $site_default_format (Default: "WG"): The card reader default token format prefix (e.g. "WG", "RF", or an array of formats).
  • $char_read_timeout (Default: 0.050): The read timeout in seconds between characters. Lowering this increases serial/socket responsiveness at the cost of higher CPU usage.
  • $keepalive_abort_count (Default: 3): The number of missed keepalives from the door controller before resetting the connection.

Database Logging (MariaDB)

  • $DB_HOST: Hostname or IP address of the database.
  • $DB_NAME: Database name (e.g. "esctl").
  • $DB_USER / $DB_PASS: Log database credentials.

LDAP / Active Directory Integration

  • $ldapServer: URL of the LDAP server (e.g. "ldap://localhost/" or array of servers).
  • $ldapGroupSearchType ("simple" or "AD"): Defines the search strategy. Use "AD" for Active Directory.
  • $ldapBaseDN: Base Distinguished Name for directory operations.
  • $ldapUser / $ldapPassword: Bind DN and credentials used to connect to LDAP.
  • $ldapGroupsDN / $ldapUsersDN: Base DN paths for groups and users.
  • $ldapTokensDN / $ldapReadersDN: Directory paths for token maps and reader definitions.

Token Security & Hashing

  • $tokenHashTypes (Default: ["sha512", "none"]): An array of hash algorithms to attempt when verifying card tokens.
  • $tokenHashSecret: Secret salt string used when generating secure hashes of tokens.

Debugging, Logging & IPC

  • $DEBUG (Default: 9): Integer level controlling syslog detail level (0 for emergency database/LDAP failures, 9 for verbose user accesses, 12+ for complete packet/object dumps).
  • $DEBUG_PROFILER (Disabled by default, e.g. #$DEBUG_PROFILER = 1;): When set to 1, prints timing diagnostics to STDERR to trace slow operations (such as LDAP search performance).
  • $DEBUG_DUMMY_LDAP: Mock hash reference specifying dummy users, groups, readers, and tokens for offline local tests.
  • $DEBUG_DUMMY_SYSLOG: Redirects syslog prints directly to STDOUT (useful during command-line testing).
  • $ERROR_LOG (Default: "/var/log/esctl_errors"): File to redirect STDERR output (useful to collect error and profiling outputs).
  • $SEMAPHORE_PATH / $SEMAPHORE_MODE (Default: "/tmp/esctl", 03770): Path and permissions for inter-process semaphore directories (strongly recommended to place on a tmpfs RAM disk).

Monitoring

The Master Controller includes monitoring capabilities for:

  • Power status of connected nodes.
  • VPN connectivity for remote sites.
  • System health and log rotation.

Table of contents