The Configuration Management Database Daemon is a lightweight HTTP server that provides a RESTful JSON API for workstations to register and manage information about attached devices. The Configuration Management Database Client or CMDBc is the complementary component that collects configuration information for attached devices and reports that information to the server for storage in the database. CMDBc can register or "check-in" attached devices with the server, obtain unique serial numbers from the server for devices that support serial number configuration, perform audits against previous device configurations, and report configuration changes found during the audit to the server for logging and analysis. CMDBd stores the information in a back-end database.
CMDBd is written in Go and can be compiled for any operating system and architecture. This document assumes CMDBd will be installed on Red Hat Enterprise Linux or CentOS release 7 -- or an equivalent operating system that supports RPM package management and the SystemD initialization system. It requires MySQL 5.7 or MariaDB 10.2 or higher for the back-end database.
You can build the RPM package with only the RPM spec file, cmdbd.spec, using the following commands:
wget https://raw.githubusercontent.com/jscherff/cmdbd/master/rpm/cmdbd.spec
rpmbuild -bb --clean cmdbd.specYou will need to install the git, golang, and rpm-build packages and their dependencies in order to perform the build. Once you've built the RPM, you can install it with this command:
rpm -i ${HOME}/rpmbuild/RPMS/{arch}/cmdbd-{version}-{release}.{arch}.rpmWhere {arch} is your system architecture (e.g. x86_64), {version} is the package version, (e.g. 1.0.0), and {release} is the package release (e.g. 1.el7.centos). The package will install the following files:
/usr/sbin/cmdbdis the CMDBd daemon./etc/cmdbd/config.jsonis the CMDBd configuration file./usr/lib/systemd/system/cmdbd.serviceis the SystemD service configuration./usr/share/doc/cmdbd-x.y.z/LICENSEis the Apache 2.0 license./usr/share/doc/cmdbd-x.y.z/README.mdis this documentation file./usr/share/doc/cmdbd-x.y.z/cmdbd.sqlis the database creation SQL./usr/share/doc/cmdbd-x.y.z/users.sqlis the application user creation SQL./var/log/cmdbdis the directory where CMDBd writes its log files.
Once the package is installed, you must create the database schema, objects, and user account on the target database server using the provided SQL, cmdb.sql and users.sql. You must also modify config.json configuration file to reflect the correct database server hostname and port, database user and password, application listener port, and other preferences (see below). By default, the config.json file is owned by the daemon user account and is not world-readable. You should not relax the permissions mode of this file as it contains the database password.
Pre-compiled binaries are also available for both 32- and 64-bit Windows systems and can be installed in any folder along with the required JSON configuration file:
cmdbd.exe(32-bit Windows Server 2008 or higher)cmdbd.exe(64-bit Windows Server 2008 or higher)config.json(Configuration file)
The JSON configuration file, config.json, is mostly self-explanatory. The default settings are sane and you should not have to change them in most use cases.
Parameters that affect the behavior of the HTTP server:
"Server": {
"Addr": ":8080",
"ReadTimeout": 10,
"WriteTimeout": 10,
"MaxHeaderBytes": 1048576,
"HttpBodySizeLimit": 1048576,
"AllowedContentTypes": ["application/json"]
}Addris the hostname or IP address and port of the listener, separated by a colon. If blank, the daemon will listen on all network interfaces.ReadTimeoutis the maximum duration in seconds for reading the entire HTTP request, including the body.WriteTimeoutis the maximum duration in seconds before timing out writes of the response.MaxHeaderBytesis the maximum size in bytes of the request header.HttpBodySizeLimitis the maximum size in bytes of the request body.AllowedContentTypesis a comma-separated list of allowed media types.
Parameters for communicating with the database server:
"Database": {
"Driver": "mysql",
"Config": {
"User": "cmdbd",
"Passwd": "K2Cvg3NeyR",
"Net": "",
"Addr": "localhost",
"DBName": "gocmdb",
"Params": null
}
}Driveris the database driver. Onlymysqlis supported.Useris the database user the daemon uses to access the database.Passwdis the database user password. The default, shown, should be changed in production.Netis the port on which the database is listening. If blank, the daemon will use the MySQL default port, 3306.Addris the database hostname or IP address.DBNameis the database schema used by the application.Paramsare additional parameters to pass to the driver (advanced).
Parameters that determine log file names and logging behavior:
"Loggers": {
"system": {
"LogFile": "system.log",
"LogFlags": ["date","time","shortfile"],
"Stdout": false,
"Stderr": false,
"Syslog": false
},
"access": {
"LogFile": "access.log",
"LogFlags": [],
"Stdout": false,
"Stderr": false,
"Syslog": true
},
"error": {
"LogFile": "error.log",
"LogFlags": ["date","time","shortfile"],
"Stdout": false,
"Stderr": false,
"Syslog": false
}
}LogFileis the filename of the log file.LogFlagsspecifies information to include in the prefix of each log entry. The following [case-sensitive] flags are supported:dateincludes date of the event inYYYY/MM/DDformat.timeincludes local time of the event inHH:MM:SS24-hour clock format.utcincludes time in UTC rather than local time.standardis shorthand fordateandtime.longfileincludes the long filename of the source file of the code that generated the event.shortfileincludes the short filename of the source file of the code that generated the event.
Stdoutcauses the daemon to write log entries to standard output (console) in addition to other destinations.Stderrcauses the daemon to write log entries to standard error in addition to other destinations.Syslogcauses the daemon to write log entries to a local or remote syslog daemon using theSyslogconfiguration settings, below.
Parameters for communicating with a local or remote syslog server:
"Syslog": {
"Protocol": "tcp",
"Port": "1468",
"Host": "localhost",
"Tag": "cmdbd",
"Facility": "LOG_LOCAL7",
"Severity": "LOG_INFO"
}Protocolis the transport-layer protocol used by the syslog daemon (blank for local).Portis the port used by the syslog daemon (blank for local).Hostis the hostname or IP address of the syslog daemon (blank for local).Tagis an arbitrary string to add to the event.Facilityspecifies the type of program that is logging the message (see RFC 5424):LOG_KERN-- kernel messagesLOG_USER-- user-level messagesLOG_MAIL-- mail systemLOG_DAEMON-- system daemonsLOG_AUTH-- security/authorization messagesLOG_SYSLOG-- messages generated internally by syslogdLOG_LPR-- line printer subsystemLOG_NEWS-- network news subsystemLOG_UUCP-- UUCP subsystemLOG_CRON-- security/authorization messagesLOG_AUTHPRIV-- FTP daemonLOG_FTP-- scheduling daemonLOG_LOCAL0-- local use 0LOG_LOCAL1-- local use 1LOG_LOCAL2-- local use 2LOG_LOCAL3-- local use 3LOG_LOCAL4-- local use 4LOG_LOCAL5-- local use 5LOG_LOCAL6-- local use 6LOG_LOCAL7-- local use 7
Severityspecifies the severity of the event (see RFC 5424):LOG_EMERG-- system is unusableLOG_ALERT-- action must be taken immediatelyLOG_CRIT-- critical conditionsLOG_ERR-- error conditionsLOG_WARNING-- warning conditionsLOG_NOTICE-- normal but significant conditionsLOG_INFO-- informational messagesLOG_DEBUG-- debug-level messages
Directory where log files are written:
"LogDir": {
"Windows": "log",
"Linux": "/var/log/cmdbd"
}Windowsis the log directory to use for Windows installations.Linuxis the log directory to use for Linux installations.
System-wide parameters:
"Options": {
"Stdout": false,
"Stderr": false,
"Syslog": false,
"RecoveryStack": false
}Stdoutcauses all logs to be written to standard output; it overridesStdoutsetting for individual logs.Stderrcauses all logs to be written to standard error; it overridesStderrsetting for individual logs.Syslogcauses all logs to be written to the configured syslog daemon; it overridesSyslogsettings for individual logs.RecoveryStackenables or suppresses writing of the stack track to the error log on panic conditions.
Once all configuration tasks are complete, the daemon can be started with the following command:
systemctl start cmdbdService access, system events, and errors are written to the following log files:
system.logrecords significant, non-error events.access.logrecords client activity in Apache Combined Log Format.error.logrecords service and database errors.
The daemon can also be started from the command line. The following command-line options are available:
-configspecifies an alternate JSON configuration file; the default is/etc/cmdbd/config.json.-stdoutcauses all logs to be written to standard output; it overridesStdoutsetting for individual logs.-stderrcauses all logs to be written to standard error; it overridesStderrsetting for individual logs.-syslogcauses all logs to be written to the configured syslog daemon; it overridesSyslogsetting for individual logs.-helpdisplays the above options with a short description.
Starting the daemon manually with console logging (using the stdout or stderr option flags) is good for troubleshooting. You must start the daemon in the context of the cmdbd user account or it will not be able to write to its log files:
sudo -u cmdbd /usr/sbin/cmdbd -stdoutYou can also start the daemon directly as root:
/usr/sbin/cmdbd -stdoutHowever, doing so can hide permissions-base issues when troubleshooting. (For security reasons, the daemon should never run as root in production; it should always run in the context of a nonprivileged account.) Manual startup example:
[root@sysadm-dev-01 ~]# sudo -u cmdbd /usr/sbin/cmdbd -help
Usage of /usr/sbin/cmdbd:
-config file
Web server configuration file (default "/etc/cmdbd/config.json")
-stderr
Enable logging to stderr
-stdout
Enable logging to stdout
-syslog
Enable logging to syslog
[root@sysadm-dev-01 ~]# sudo -u cmdbd /usr/sbin/cmdbd -stdout
system 2017/09/30 09:55:38 main.go:62: Database "10.2.9-MariaDB" (cmdbd@localhost/gocmdb) using "mysql" driver
system 2017/09/30 09:55:38 main.go:63: Server started and listening on ":8080"The following tables comprise the database:
- Device Checkins contains all device registrations. Multiple check-ins will create multiple records. This provides the ability to track device configuration changes over time.
- Serialized Devices contains devices with serial numbers. It is populated automatically upon device check-in. It uses a unique index based on Vendor ID, Product ID, and Serial Number, and has only one record per serialized device. The first check-in creates the record; subsequent check-ins update modified configuration settings (if any), update the record's Last Seen timestamp, and increment the record's Checkins counter.
- Unserialized Devices contains devices without serial numbers. It is populated automatically upon device check-in. It uses a unique index based on Hostname, Vendor ID, Product ID, Bus Number, Bus Address, and Port Number, and strives to have as few records as possible per unserialized device, though this cannot be guaranteed if a device is move to a different workstation or to a different port on the same workstation. The first check-in creates the record; subsequent check-ins update modified configuration settings (if any), update the record's Last Seen timestamp, and increment the record's Checkins counter.
- Serial Number Requests contains all requests for a new serial number. CMDBd updates new request records with the issued serial number after it is generated. Multiple requests will create multiple records. This provides the ability to detect failures in device serial number configuration and also detect fraudulent usage and abuse.
- Device Changes contains configuration changes detected during device audits. Each device configuration attribute change detected during an audit creates one record.
The Device Checkins, Serialized Devices, Unserialized Devices, and Serial Number Requests tables have the following columns:
- Hostname
- Vendor ID
- Product ID
- Serial Number
- Vendor Name
- Product Name
- Product Version
- Software ID
- Bus Number
- Bus Address
- Port Number
- Buffer Size
- Max Packet Size
- USB Specification
- USB Class
- USB Subclass
- USB Protocol
- Device Speed
- Device Version
- Factory Serial Number
The Device Checkins table includes the following additional column:
- Checkin Date
The Serial Number Requests table includes the following additional column:
- Request Date
The Serialized Devices and Unserialized Devices tables both include the following additional columns:
- First Seen
- Last Seen
- Checkins
The Device Changes table has the following columns:
- Host Name
- Vendor ID
- Product ID
- Serial Number
- Changes
For a given Device Changes record, the Changes column contains a JSON object that represents a collection of one or more changes. Each change element in the collection has the following fields:
- Property Name
- Old Value
- New Value
| Endpoint | Method | Purpose |
|---|---|---|
/usbci/checkin/{host}/{vid}/{pid} |
POST | Submit configuration information for a new device or update information for an existing device. |
/usbci/checkout/{host}/{vid}/{pid}/{sn} |
GET | Obtain configuration information for a previously-registered, serialized device in order to perform a change audit. |
/usbci/audit/{host}/{vid}/{pid}/{sn} |
POST | Submit the results of a change audit on a serialized device. Results include the attribute name, previous value, and new value for each modified attribute. |
/usbci/newsn/{host}/{vid}/{pid} |
POST | Obtain a new unique serial number from the server for assignment to the attached device. |
hostis the hostname of the workstation to which the device is attached.vidis the vendor ID of the device.pidis the product ID of the device.snis the serial number of the device.