Creator

Documentation index

CMDB follows MyCount’s control-server installation pattern: a dedicated Linux account, a local MariaDB database, a Python virtual environment, and a systemd service. Run installation from a checkout separate from /opt/prod/cmdb.

Prerequisites

The target machine needs Python 3.11 or later with virtual-environment support, MariaDB server and client, and systemd. MariaDB must be running with root administrative access through its local socket. Python dependencies are downloaded during installation. On Debian/Ubuntu, the maintainer can prepare the system with:

sudo apt install python3 python3-venv mariadb-server mariadb-client nmap sudo openssh-client cron
sudo systemctl enable --now mariadb

Install

From the checkout:

sudo scripts/install.sh

The installer creates the cmdb Linux service account and the cmdb database and database account. It generates /etc/cmdb/database.env owned by root with group cmdb and mode 640, so the standalone cron runner can read it. Existing root-only mode 600 files are adjusted on installation or upgrade. Repeated installation reuses the credentials without resetting an existing database password. An existing account with different credentials causes installation to fail; it is not silently taken over.

The local cmdb account uses /var/lib/cmdb as its home, retaining its nologin shell. The installer generates an Ed25519 SSH key without a passphrase for unattended outbound connections:

  • Private key: /var/lib/cmdb/.ssh/id_ed25519 (mode 600).
  • Public key: /var/lib/cmdb/.ssh/id_ed25519.pub (mode 644).
  • Known hosts: /var/lib/cmdb/.ssh/known_hosts (mode 600).

These files belong to cmdb; .ssh has mode 700. Reinstallation reuses the private key and known hosts. A missing public key is reconstructed from the private key. An invalid or encrypted existing private key causes installation to fail without replacing it. The service can write its SSH directory under the otherwise read-only system filesystem configuration.

Remote accounts and public-key authorization are not configured by the installer. The scanner’s SSH follow-up can provision remote cmdb access when root already accepts this public key. The same key supports remote cmdbagent or root login when authorized by the remote account. Selecting remote root in the SSH interface requires no additional local sudoers rule or separate key. See SSH interface for usage.

Installation and upgrade validate and install /etc/sudoers.d/cmdb-nmap, owned by root with mode 0440, containing:

cmdb ALL=(root) NOPASSWD: /usr/bin/nmap
cmdb ALL=(cmdbagent) NOPASSWD: /bin/sh

This grants the cmdb user passwordless root access to Nmap with unrestricted arguments. The Nmap interface uses python-nmap’s sudo=True option, with the executable fixed to /usr/bin/nmap. The service sets NoNewPrivileges=false to allow sudo; the Python server itself continues to run as cmdb.

Application files are copied to /opt/prod/cmdb, with Python dependencies in .venv, including python-crontab. It also copies cmdb-backup.py and enables the system cron service. The CMDB service can update its own crontab through the standard crontab helper; its sandbox permits writes to /var/spool/cron/crontabs. The installer checks the database connection, installs cmdb-server.service, enables it at boot, starts it, and checks /health and /ready. Open http://<server>:14444/ afterward.

The installer applies schema/cmdb-schema-v1.sql to the database. It creates the Machine table if absent, preserving existing rows on repeat installation. id is the shared primary key inherited from Namespace and ModelElement; ModelElement allocates the auto-increment identity. ipAddress remains unique (VARCHAR(45), accommodating IPv4 and IPv6) for scan matching. macAddress is nullable VARCHAR(17). hostName and site are nullable VARCHAR(255) columns, matching the Machine entity’s attribute casing. createdOn and updatedOn record insertion and the latest discovery update in UTC. Edit the SQL file to maintain the fresh-install schema. During initial development, it does not migrate existing tables. After a schema change, use uninstall/install to recreate the database and let discovery populate it.

DeployedComponent stores each deployment’s pathname, machine foreign key to Machine.id, and required component reference to Component.id, with an identity shared with its Namespace and ModelElement parent records. A machine can contain zero or more component rows. The foreign key rejects components for unknown machines and prevents deleting a machine while components reference it. Changing a machine’s IP address does not change its ID or component links. SoftwareSystem owns Component through ModelElement.namespace and the inverse Namespace.ownedElement relationship. These tables hold the OS software deployment model. Machine.deployedComponent is derived from the foreign-key relationship rather than stored as a text column on Machine.

Upgrade

From the updated checkout:

sudo scripts/upgrade.sh

Upgrade reuses the installation process, preserving credentials and database data when the schema is unchanged. For schema changes at this stage, use scripts/uninstall.sh followed by scripts/install.sh instead. The service stops before dependencies and application files are updated. A failure can leave it stopped; correct the reported issue and rerun the command. Deployment does not provide automatic rollback.

Uninstall

From the separate checkout:

sudo scripts/uninstall.sh

This stops and disables the service, removes CMDB-owned backup and patch cron entries while preserving unrelated entries, drops the cmdb database (including all inventory), and removes the service unit, /opt/prod/cmdb, and the Nmap sudoers rule. It retains /etc/cmdb/database.env, the MariaDB account and password, and the Linux service account and group for reinstallation. /var/lib/cmdb, including the SSH key and known-hosts file, is retained too.

The checkout and system packages (including MariaDB and Nmap) remain installed. Uninstall requires local MariaDB root access. It can be rerun from the checkout after a partial uninstall and stops on errors. If dropping the database fails, the service remains stopped and the application files remain in place.

Runtime configuration

Paths, account names, and the default listener 0.0.0.0:14444 are defined in cmdb/constants/DCMDB.py. DCMDB.CMDB_NETWORK declares the listener as a literal ("http", "0.0.0.0", 14444) tuple of use, interface, and port. The service is intended for a trusted LAN. It has no authentication and installation does not add a public proxy or router mapping.

Installation creates /opt/prod/cmdb/conf/cmdb.json from these defaults. Reinstall and upgrade preserve existing configuration. To override the HTTP listener, edit the production file, for example:

{
  "network": {
    "http": {
      "interface": "127.0.0.1",
      "port": 14445
    }
  }
}

The interface must be an IPv4 address and the port an integer from 1 to 65535. Omitted uses and fields inherit CMDB_NETWORK defaults; a missing file uses all defaults. Unknown settings and invalid values fail validation. The constants declare default inventory; JSON and command-line overrides do not change that declaration. Network discovery support is deferred.

For applying this standard to another app, see the CMDB_NETWORK app developer guide.

Apply edits with the installed restart command:

sudoedit /opt/prod/cmdb/conf/cmdb.json
cd /opt/prod/cmdb
sudo ./scripts/restart.sh

The command validates configuration before restarting the web server. Each process loads settings once, so edits take effect on restart. The server’s --host and --port arguments override the resolved settings for an individual invocation. Installation health checks use the resolved binding, substituting loopback for 0.0.0.0. Uninstall removes this configuration with the application.

Systemd reads /etc/cmdb/database.env before starting the unprivileged process. The file contains DB_HOST, DB_PORT, DB_NAME, DB_USER, and DB_PASSWORD. These outbound database settings remain separate from listener configuration. Keep the credentials private and out of this repository.

See CMDB server for endpoints, status commands, and development startup.

Inventory account

Install and upgrade retain the cmdb service identity and SSH key, and provision local cmdbagent with home /var/lib/cmdbagent. The sudo rule also permits cmdb to execute local inventory commands as cmdbagent. Remote discovery uses cmdbagent with the existing key. See the one-time remote account cleanup for removing the old remote cmdb accounts and homes after upgrade. Uninstall retains both local accounts and their homes.

The installer also provisions MariaDB’s cmdbagent@localhost using socket authentication and grants SHOW DATABASES, SELECT, SHOW VIEW, TRIGGER, and EVENT for inventory and dumps. It verifies access as Linux cmdbagent. This runs on upgrade as well as fresh installation and uses schema/cmdbagent.sql. The existing application database credentials are retained.

For manual backups, each database host needs mariadb-dump, flock, and the standard coreutils commands. The configured backup directory may use autofs/NFS or local storage, and cmdbagent must be able to create files there. The installer does not configure mounts or NFS permissions. The service grants write access to the configured backup directory for local neuromancer dumps. See manual backups.

Debian patch runner

Installation also enables cmdb-patch.service, independent of the web service, and installs fixed local sudo actions for patching and rebooting. The normal installer creates its job storage. Uninstall stops both services. See Debian patching for execution and recovery behavior.