cmdbc

README

CMDBc

The Configuration Management Database Client or CMDBc is a utility that manages information about devices attached to end-user workstations and reports that information to a centralized repository over a RESTful JSON API provided by the complementary server component, the Configuration Management Database Daemon or CMDBd. Detailed documentation for CMDBd is located here.

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.

System Requirements

CMDBc is written in Go and can be compiled for any operating system and architecture. It is intended to be installed on end-user workstations running Microsoft Windows 7 or higher and should be invoked by a centralized management solution like IBM BigFix.

Installation

To implement CMDBc quickly with minimal configuration, please see the QuickStart document.

Pre-compiled binaries are available for both 32- and 64-bit Windows systems and can be installed in any folder along with the required JSON configuration file:

• cmdbc.exe (32-bit Windows 7 or higher)
• cmdbc.exe (64-bit Windows 7 or higher)
• config.json (Configuration file)

Configuration

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.

Client Settings

The Client section of the configuration file contains parameters for the HTTP client.

"Client": {
    "Timeout": 0,
    "IdleConnTimeout": 0,
    "ResponseHeaderTimeout": 0,
    "MaxResponseHeaderBytes": 0
}

• Timeout specifies the time limit in seconds for requests made by the Client. The timeout includes connection time, any redirects, and reading the response body. The timer remains running after Get, Head, Post, or Do return and will interrupt reading of the Response.Body. A value of zero means "no limit."
• IdleConnTimeout is the maximum amount of time in seconds a keep-alive connection will remain idle before closing itself. A value of zero means "no limit."
• ResponseHeaderTimeout specifies the amount of time in seconds to wait for a server's response headers after fully writing the request, including its body, if any. This does not include the time to read the response body. A value of zero means "no limit."
• MaxResponseHeaderBytes specifies the maximum size in bytes of the server's response header. A value of zero means "use the default limit."

Server Settings

The Server section of the configuration file contains parameters for communicating with the CMDBd server and URL paths for the REST API endpoints.

"Server": {
    "Protocol": "http",
    "HostName": "cmdbsvcs.24hourfit.com",
    "Port": "8080",
    "Auth": {
        "Username": "clubpc",
        "Password": "****************"
    },
    "Endpoints": {
        "cmdb_auth": "/v2/cmdb/authenticate/%s",
        "usb_ci_checkin": "/v2/cmdb/ci/usb/checkin/%s/%s/%s",
        "usb_ci_checkout": "/v2/cmdb/ci/usb/checkout/%s/%s/%s/%s",
        "usb_ci_newsn": "/v2/cmdb/ci/usb/newsn/%s/%s/%s",
        "usb_ci_audit": "/v2/cmdb/ci/usb/audit/%s/%s/%s/%s",
        "usb_meta_vendor": "/v2/cmdb/meta/usb/vendor/%s",
        "usb_meta_product": "/v2/cmdb/meta/usb/product/%s/%s",
        "usb_meta_class": "/v2/cmdb/meta/usb/class/%s",
        "usb_meta_subclass": "/v2/cmdb/meta/usb/subclass/%s/%s",
        "usb_meta_protocol": "/v2/cmdb/meta/usb/protocol/%s/%s/%s"
    }
}

• Protocol is the TCP protocol used for communicating with the server.
• HostName is the host name or IP address of the server.
• Port is the TCP port on which the server is listening.
• Auth contains the credentials the client will use to authenticate with the server using basic authentication.
  • Username is the username component of the client credentials. The default is shown.
  • Password is the password component of the client credentials.
• Endpoints is a collection of URL paths that represent the base of the REST API endpoints on the server. The API endpoints and their parameters are described more fully in the API Endpoints section of the server documentation. You should not modify anything in this section unless asked to do so by a systems administrator or application designer.
  • cmdb_auth is the base path of the API on which the client authenticates using basic authentication (see Auth, above). On successful authentication, the server will issue token (JWT) that the client will use to access protected endpoints for the remainder of the session.
  • usb_ci_checkin is the base path of the API on which the client submits configuration information for a new device or update information for an existing device.
  • usb_ci_checkout is the base path of the API on which the client obtains configuration information for a previously-registered, serialized device in order to perform a change audit.
  • usb_ci_newsn is the base path of the API on which the client obtains a new unique serial number from the server for assignment to the attached device.
  • usb_ci_audit is the base path of the API on which the client 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.
  • usb_meta_vendor is the base path of the API on which the client obtains the USB vendor name by providing the vendor ID.
  • usb_meta_product is the base path of the API on which the client obtains the USB vendor and product names by providing the vendor and product IDs.
  • usb_meta_class is the base path of the API on which the client obtains the USB class description by providing the class ID.
  • usb_meta_subclass is the base path of the API on which the client obtains the USB class and subclass descriptions by providing the class and subclass IDs.
  • usb_meta_protocol is the base path of the API on which the client obtains the USB class, subclass, and protocol descriptions by providing the class, subclass, and protocol IDs.

Path Settings

The Paths section of the configuration file specifies directories where various files will be written. Relative paths are prepended with the installation directory.

"Paths": {
    "ReportDir": "report"
}

• ReportDir is where device reports are written. This can be overridden with the folder report option flag.

Logger Settings

The Loggers section of the configuration file contains logging options for the system, change, and error log.

"Loggers": {

    "LogDir": "log",
    "Console": false,
    "Syslog": false,
    
    "Logger": {
        "system": {
            "LogFile": "system.log",
            "Console": false,
            "Syslog": false,
            "Prefix": ["date", "time"]
        },
        "change": {
            "LogFile": "change.log",
            "Console": false,
            "Syslog": false,
            "Prefix": ["date", "time"]
        },
        "error": {
            "LogFile": "error.log",
            "Console": true,
            "Syslog": false,
            "Prefix": ["date", "time", "file"]
        }
    }
}

• LogDir is the directory where logs files will be written.
• Console causes the utility to write events to the console (stdout) in addition to the log file. This overrides the same setting for individual logs, below.
• Syslog causes the utility to write events to a local or remote syslog daemon using the Syslog configuration settings (see Syslog Settings, below).
• Logger is a collection of logs used by the utility to record events.
  • system contains settings for the system log, where the utility records significant, non-error events.
  • change contains settings for the change log, where the utility records changes found during audits. It also reports changes to the server.
  • error contains settings for the error log, where the utility records critical errors.

Each logger, above, has the following configuration settings:

• LogFile specifies the filename of the log file.
• Console specifies whether or not events are written to the console (stdout) in addition to the log file.
• Syslog causes the utility to write events to a local or remote syslog daemon using the Syslog configuration settings (see Syslog Settings, below).
• Prefix is a comma-separated list of optional attributes that will be prepended to each log entry:
  • date is the date of the event in YYYY/MM/DD format.
  • time is the local time of the event in HH:MM:SS format.
  • file is the name of the file containing the source code that produced the event.

Syslog Settings

The Syslog section contains parameters for communicating with a local or remote syslog server. Please note that the syslog daemon, if not running on the same host as the utility, must be configured to accept remote syslog client connections.

"Syslog": {
    "Enabled": false,
    "Protocol": "udp",
    "Port": "514",
    "Host": "localhost",
    "Tag": "usbci_cmdbc",
    "Facility": "LOG_LOCAL7",
    "Severity": "LOG_INFO"
}

• Enabled specifies whether or not syslog logging is available to the loggers. If syslog logging is not enabled, the loggers will not write to the configured syslog daemon, even if they're configured to do so.
• Protocol is the transport-layer protocol used by the syslog daemon (blank for local).
• Port is the port used by the syslog daemon (blank for local).
• Host is the hostname or IP address of the syslog daemon (blank for local).
• Tag is an arbitrary string to prepend to the syslog event.
• Facility specifies the type of program that is logging the message (see RFC 5424):
  • LOG_KERN -- kernel messages
  • LOG_USER -- user-level messages
  • LOG_MAIL -- mail system
  • LOG_DAEMON -- system daemons
  • LOG_AUTH -- security/authorization messages
  • LOG_SYSLOG -- messages generated internally by syslogd
  • LOG_LPR -- line printer subsystem
  • LOG_NEWS -- network news subsystem
  • LOG_UUCP -- UUCP subsystem
  • LOG_CRON -- security/authorization messages
  • LOG_AUTHPRIV -- FTP daemon
  • LOG_FTP -- scheduling daemon
  • LOG_LOCAL0 -- local use 0
  • LOG_LOCAL1 -- local use 1
  • LOG_LOCAL2 -- local use 2
  • LOG_LOCAL3 -- local use 3
  • LOG_LOCAL4 -- local use 4
  • LOG_LOCAL5 -- local use 5
  • LOG_LOCAL6 -- local use 6
  • LOG_LOCAL7 -- local use 7
• Severity specifies the severity of the event (see RFC 5424):
  • LOG_EMERG -- system is unusable
  • LOG_ALERT -- action must be taken immediately
  • LOG_CRIT -- critical conditions
  • LOG_ERR -- error conditions
  • LOG_WARNING -- warning conditions
  • LOG_NOTICE -- normal but significant conditions
  • LOG_INFO -- informational messages
  • LOG_DEBUG -- debug-level messages

Include Settings

The Include section specifies device vendors and products to include (true) or exclude (false) when conducting inventories.

"Include": {
    "VendorID": {
        "0801": true,
        "043d": false,
        "045e": false
    },
    "ProductID": {
        "0acd": {
            "2010": true,
            "2030": true
        },
        "046a": {
            "0001": true
        }
    },
    "Default": true
}

• VendorID specifies which vendors to include or exclude. This setting applies to all of the vendor's products and overrides both the ProductID and Default configuration settings; that is, if a vendor is excluded under VendorID, that vendor's products cannot be included under the ProductID or Default sections. Here, all Magtek devices (vendor ID "0801") will be included, whereas Microsoft devices (vendor IDs "043d" and "045e") will be excluded.
• ProductID specifies individual products to include or exclude. This setting applies to specific ProductIDs under a given VendorID and overrides the Default configuration setting. Here, IDTech card readers (vendor ID "0acd," product IDs "2010" and "2030") will be included, as will Cherry keyboards (vendor ID "046a," product ID "0001").
• Default specifies the default behavior for products that are not specifically included or excluded by Vendor ID or Product ID. Here the default is to include, which effectively renders previous inclusions redundant; however, specific VendorID and ProductID inclusions ensure that those devices will be inventoried even if the Default setting is changed to 'exclude' (false).

Command-Line Flags

Client operation is controlled through command-line flags. There are eight top-level action flags -- audit, checkin, report, reset, serial, state, version, and help. Some of these require (or offer) additional option flags.

• -audit performs a device configuration change audit.
• -checkin checks devices in with the server, which stores device information in the database along with the check-in date.
• -report generates device configuration reports.
  • -console writes report output to the console.
  • -folder <path> writes report output files to <path>. It defaults to the report folder beneath the installation directory.
  • -format <format> specifies which report <format> to use:
    • csv specifies comma-separated value format.
    • nvp specifies name-value pair format.
    • xml specifies extensible markup language format.
    • json specifies JavaScript object notation format (default).
  • -help lists report option flags and their descriptions.
• -reset resets the device.
• -serial performs serial number operations, if supported. (By default, the utility will not configure a serial number on a device that already has one.)
  • -default sets the serial number to the factory default (if present).
  • -erase erases the current serial number.
  • -fetch fetches a unique serial number from the server.
  • -force forces a serial number change, even if the device already has one.
  • -set <value> sets serial number to the specified <value>.
  • -help lists serial option flags and their descriptions.
• -state shows the current operating state of the device, if supported.
• -version displays the version of the client utility.
• -help lists top-level action flags and their descriptions.

Serial Number Configuration

Configure serial numbers on attached devices with the serial action flag.

The fetch, default, and set option flags are mutually-exclusive. If you use more than one, fetch will take highest precedence, followed by default and set.

The fetch, default, and set option flags can each be combined with erase and force. By default, the utility ignores serial number changes for devices that already have one. The erase option flag bypasses this by erasing the existing serial number before attempting to assign a new one, effectively removing the constraint. The force option flag simply overrides the safeguard feature.

Examples:

cmdbc.exe -serial -fetch

The preceding command will, for each compatible device, fetch a new serial number from the server and configure the device with it -- but only for devices that do not already have a serial number. This is the safe and preferred method for assigning unique serial numbers to unserialized devices.

cmdbc.exe -serial -fetch -force

The preceding command will, for each compatible device, fetch a new serial number from the server and configure the device with it, overriding the safety mechanism that prevents overwriting existing serial numbers.

cmdbc.exe -serial -erase -fetch

The preceding command will, for each compatible device, erase the existing serial number, fetch a new, unique serial number from the server, and configure the device with it.

While the previous two examples would normally produce the same result, a subtle difference is that, if the utility were unable to obtain a new serial number, force would leave existing serial numbers in place whereas erase would leave devices without serial numbers.

You can also use the erase option flag by itself to erase device serial numbers, although this is an unusual use case.

Caution: action and option flags apply to all attached devices. As noted above, if you use the serial action flag with the fetch option flag, the utility will only configure new serial numbers on compatible devices that don't already have one. If all attached devices already have serial numbers or are not configurable, nothing will happen. However, if you add the force flag, it will overwrite the serial number on all compatible devices -- even those that already have a serial number. If you use the set and force option flags and there is more than one configurable device attached, you will end up having multiple devices with the same serial number.

Refer to the Database Structure section in the CMDBd documentation for details on device information transferred to the server and tables/columns affected by serial number requests.

Device Registration

Register attached devices with the server using the checkin action flag. This will create a new object in the device repository.

Refer to the Database Structure section in the CMDBd documentation for details on device information transferred to the server and tables/columns affected by device registrations.

Device Audits

Perform a configuration change audit for attached devices using the audit action flag. During an audit, device configurations are compared against those stored on the server for the previous device check-in. Changes detected during an audit are written to the local change log and are also reported to the server. Audits are only supported on serialized devices.

Refer to the Database Structure section in the CMDBd documentation for details on device information transferred to the server and tables/columns affected by device audits.

Device Reports

Generate device reports for attached devices using the report action flag.

Select the report format with the format option flag. Four formats are currently supported: comma-separated value (CSV), name-value pairs (NVP), extensible markup language (XML), and JavaScript object notation (JSON). JSON is the default format.

By default, report files are written to the report subdirectory under the utility installation directory (configurable). A separate report file is generated for each device. The report filename is P{pn}-B{bn}-V{vid}-P{pid}.{fmt}, where

• pn is a two-digit hexadecimal value representing port number,
• bn is a two-digit hexadecimal value representing bus number,
• vid is a four-digit hexadecimal value representing vendor ID,
• pid is a four-digit hexadecimal value representing product ID, and
• fmt is the report format (csv, nvp, xml, or json)

Change the report destination folder with the folder option flag.

Write the report to the console with the console option flag. If you use the console option flag, the report will only be written to the console and folder option flag, if used, will be ignored.

Examples:

cmdbc.exe -report -console

The preceding command writes the device reports to the console in JSON format (the default format).

cmdbc.exe -report -format csv

The preceding command writes the device reports in CSV format to the 'reports' subdirectory under the utility installation folder (the default report folder).

cmdbc.exe -report -format nvp -folder c:\reports

The preceding command writes the device reports in NVP format to the c:\reports folder.

cmdbc.exe -report -format xml -console
cmdbc.exe -report -format xml -console -folder c:\reports

Both of the preceding commands write the device reports in XML format to the console. The folder option flag in the second command is ignored because console option flag was used.

Device Resets

Reset attached devices using the reset action flag. Depending on the device, this either does a host-side reset, refreshing the USB device descriptor, or a low-level hardware reset on the device.