Configuration of BIRD is complex, yet straightforward. There are three modules taking care of the configuration: config manager (which takes care of storage of the config information and controls switching between configs), lexical analyzer and parser.
The configuration manager stores each config as a config structure accompanied by a linear pool from which all information associated with the config and pointed to by the config structure is allocated.
There can exist up to four different configurations at one time: an active one (pointed to by config), configuration we are just switching from (old_config), one queued for the next reconfiguration (future_config; if it's non-NULL and the user wants to reconfigure once again, we just free the previous queued config and replace it with the new one) and finally a config being parsed (new_config).
Loading of new configuration is very simple: just call config_alloc() to get a new config structure, then use config_parse() to parse a configuration file and fill all fields of the structure and finally ask the config manager to switch to the new config by calling config_commit().
CLI commands are parsed in a very similar way -- there is also a stripped-down config structure associated with them and they are lex-ed and parsed by the same functions, only a special fake token is prepended before the command text to make the parser recognize only the rules corresponding to CLI commands.
struct config * config_alloc (byte * name) -- allocate a new configuration
name of the config
This function creates new config structure, attaches a resource pool and a linear memory pool to it and makes it available for further use. Returns a pointer to the structure.
int config_parse (struct config * c) -- parse a configuration
configuration
config_parse() reads input by calling a hook function pointed to by cf_read_hook and parses it according to the configuration grammar. It also calls all the preconfig and postconfig hooks before, resp. after parsing.
1 if the config has been parsed successfully, 0 if any error has occurred (such as anybody calling cf_error()) and the err_msg field has been set to the error message.
int cli_parse (struct config * c) -- parse a CLI command
temporary config structure
cli_parse() is similar to config_parse(), but instead of a configuration, it parses a CLI command. See the CLI module for more information.
void config_free (struct config * c) -- free a configuration
configuration to be freed
This function takes a config structure and frees all resources associated with it.
int config_commit (struct config * c, int type) -- commit a configuration
new configuration
type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
When a configuration is parsed and prepared for use, the config_commit() function starts the process of reconfiguration. It checks whether there is already a reconfiguration in progress in which case it just queues the new config for later processing. Else it notifies all modules about the new configuration by calling their commit() functions which can either accept it immediately or call config_add_obstacle() to report that they need some time to complete the reconfiguration. After all such obstacles are removed using config_del_obstacle(), the old configuration is freed and everything runs according to the new one.
CONF_DONE if the configuration has been accepted immediately, CONF_PROGRESS if it will take some time to switch to it, CONF_QUEUED if it's been queued due to another reconfiguration being in progress now or CONF_SHUTDOWN if BIRD is in shutdown mode and no new configurations are accepted.
void order_shutdown (void) -- order BIRD shutdown
This function initiates shutdown of BIRD. It's accomplished by asking for switching to an empty configuration.
void cf_error (char * msg, ... ...) -- report a configuration error
printf-like format string
variable arguments
cf_error() can be called during execution of config_parse(), that is from the parser, a preconfig hook or a postconfig hook, to report an error in the configuration.
char * cfg_strdup (char * c) -- copy a string to config memory
string to copy
cfg_strdup() creates a new copy of the string in the memory pool associated with the configuration being currently parsed. It's often used when a string literal occurs in the configuration and we want to preserve it for further use.
The lexical analyzer used for configuration files and CLI commands
is generated using the flex
tool accompanied by a couple of
functions maintaining the hash tables containing information about
symbols and keywords.
Each symbol is represented by a symbol structure containing name of the symbol, its lexical scope, symbol class (SYM_PROTO for a name of a protocol, SYM_NUMBER for a numeric constant etc.) and class dependent data. When an unknown symbol is encountered, it's automatically added to the symbol table with class SYM_VOID.
The keyword tables are generated from the grammar templates
using the gen_keywords.m4
script.
struct symbol * cf_find_symbol (byte * c) -- find a symbol by name
symbol name
This functions searches the symbol table for a symbol of given name. First it examines the current scope, then the second recent one and so on until it either finds the symbol and returns a pointer to its symbol structure or reaches the end of the scope chain and returns NULL to signify no match.
struct symbol * cf_define_symbol (struct symbol * sym, int type, void * def) -- define meaning of a symbol
symbol to be defined
symbol class to assign
class dependent data
Defines new meaning of a symbol. If the symbol is an undefined one (SYM_VOID), it's just re-defined to the new type. If it's defined in different scope, a new symbol in current scope is created and the meaning is assigned to it. If it's already defined in the current scope, an error is reported via cf_error().
Pointer to the newly defined symbol. If we are in the top-level scope, it's the same sym as passed to the function.
void cf_lex_init (int is_cli) -- initialize the lexer
true if we're going to parse CLI command, false for configuration
cf_lex_init() initializes the lexical analyzer and prepares it for parsing of a new input.
void cf_push_scope (struct symbol * sym) -- enter new scope
symbol representing scope name
If we want to enter a new scope to process declarations inside a nested block, we can just call cf_push_scope() to push a new scope onto the scope stack which will cause all new symbols to be defined in this scope and all existing symbols to be sought for in all scopes stored on the stack.
void cf_pop_scope (void) -- leave a scope
cf_pop_scope() pops the topmost scope from the scope stack, leaving all its symbols in the symbol table, but making them invisible to the rest of the config.
char * cf_symbol_class_name (struct symbol * sym) -- get name of a symbol class
symbol
This function returns a string representing the class of the given symbol.
Both the configuration and CLI commands are analyzed using a syntax
driven parser generated by the bison
tool from a grammar which
is constructed from information gathered from grammar snippets by
the gen_parser.m4
script.
Grammar snippets are files (usually with extension .Y
) contributed
by various BIRD modules in order to provide information about syntax of their
configuration and their CLI commands. Each snipped consists of several
sections, each of them starting with a special keyword: CF_HDR
for
a list of #include
directives needed by the C code, CF_DEFINES
for a list of C declarations, CF_DECLS
for bison
declarations
including keyword definitions specified as CF_KEYWORDS
, CF_GRAMMAR
for the grammar rules, CF_CODE
for auxiliary C code and finally
CF_END
at the end of the snippet.
To create references between the snippets, it's possible to define
multi-part rules by utilizing the CF_ADDTO
macro which adds a new
alternative to a multi-part rule.
CLI commands are defined using a CF_CLI
macro. Its parameters are:
the list of keywords determining the command, the list of parameters,
help text for the parameters and help text for the command.
Values of enum
filter types can be defined using CF_ENUM
with
the following parameters: name of filter type, prefix common for all
literals of this type and names of all the possible values.