Blackbird

Setting up your Config Files

Running a Blackbird begins by enabling its process configurations. The way a Blackbird loads a process begins with the lib/Blackbird/configuration/ directory. Upon starting, Blackbird will scan the /path/to/Blackbird/configuration/install/ directory for all .cfg files. Each configuration is a reference to a process file, the code for which is stored in the /path/to/Blackbird/processes/ directory. Each config file is required to contain:

A Process Name, unique across all modules, which references the instance of a process.
A Process Type, which is a reference to a process within the processes directory.

Within the configuration directory is a "staging" folder. This is where all configuration files reside when not in active use. To enable a process, move its configuration file from the "staging" directory to the "install" directory. When you start up your Blackbird, it will load all modules in the install directory.

Starting a Nest Server

The first step to running a Blackbird is to start your nest server. On linux, open a new terminal window and start an instance of the nest. (Note: This assumes you have already configured your Nest Server.) To start an instance of nest, simply execute it from the command line using php (php -q /path/to/Nest/nest.php). This will begin a nest server, allowing you to monitor all the connections from your users. Once your nest is up and running, you're ready to start a Blackbird.

Starting a Blackbird

To start a Blackbird, execute the processor file in the source code of the Blackbird directory from the command line using php (php -q /path/to/Blackbird/src/processor.php), which will start up a Blackbird. By default, Blackbird outputs its metrics as a serialized array to the terminal every 5 seconds (the granularity of metrical output is controlled in the blackbird.conf file). While not ideal, it gives you an idea of how to retrieve and view metrical information. This will be updated and sent to a management console for Blackbird when it is completed, as it is currently under active development and not yet stable for release.

Once your Blackbird starts, it loads all the config files in the /path/to/Blackbird/configuration/install/ directory, and attempts to validate them. Validation is made possible through the Environment Stability Manager's "birdseed" class, which controls all the configuration documents. Within each process are a list of required and optional parameters within the configuration documents which are used in validation. If your configuration file is validated, an instance of the process is loaded into Blackbird and run in the defined execution cycle (which occurs through a service() call every second), and the configuration file is moved to the /path/to/Blackbird/configuration/loaded/ directory. If, however, the configuration file cannot be validated, the file is moved to the /path/to/Blackbird/configuration/error directory.

If Blackbird is stopped for any reason, the currently loaded configuration data is lost, and Blackbird must recreate new instances of the processors upon being started again. If a Blackbird is started after it has loaded configuration files, any files within the /path/to/Blackbird/configuration/loaded/ directory will be reloaded and revalidated.

Managing a Blackbird

Most management of a blackbird is two fold. The first fold is adding configuration files to the /path/to/Blackbird/configuration/install/ directory (which will be loaded, even if a Blackbird has already started), which adds new processes to the Blackbird. The second fold is through statechanges, handled by the Nest. To change the state of a Blackbird, you must log into the Nest as a Motherbird. Motherbirds are user or system-controlled entities which control the state of a blackbird. Details on this can be found within the /path/to/Nest/ directory within the configuration, permissions, and handling files.

Information is the most important part of learning, which is why Blackbird keeps its own internal logs. Please see "Logging Considerations" in the Configuration Page to find where these logs are kept.