Today we are going to talk about the Configuration Object Dictionary and specifically about the Configuration Files section.


In almost every PoC or implementation we find that we need to add, modify or remove entries from a text file. Many times these are just standard files like /etc/hosts files or .ini files for which we have standard grammars, but what if we need to add new Configuration Files entries into the Configuration Object Database and we don't have the grammar? Then we can do two things:

1. Try to satisfy the customer with a presentation of the file using one of the standard grammars.

2. Write a new grammar.


We tend to go for option 1, but you know, writing a grammar is not as difficult as it looks.


So let's do it!


First let's take a look how grammar actually work by taking a very simple one like the basically parses a file line by line and displays it as Configuration File entries.



# - generic line pass through grammar that allows

# parameter substitution.


# - 7/31/03


# Each line is parsed as one field






comment COMMENT $save_as_comment $0

record LINE $new_field $0 $save_record $0 $set_add_rule $0


add $write_field $0



So what do we see here?


Each grammar file contains four sections separated by the %% symbols:

  • Variable definitions
  • Token definitions
  • Rules
  • Add-Rules



Variables are simple to understand. Just like in any other programming language you specify a variable name and an assigned value. In this example we don't use variables. We will introduce them later.



Tokens are defined by regular expressions. In our example the token COMMENT stands for everything that comes after a # and the LINE token contains everything that doesn't have a # in front of it.

These regex are very basic. In a further example we will use more complex regular expressions. Regular expressions look very cryptic, but they aren't. Learn them. You need them everywhere. When you are writing a shell or Perl scripts, when you write grammars in BSA, when you work with BNA, etc. etc.

If you need a good tutorial on regular expressions, look here:



Rules define if a line in a textile gets displayed or not. Rules have a name and contain Tokens, actions and arguments. In our example we have two rules called "comment" and "record". These two rule get checked in sequential order and if a match is found, the line will be displayed.


Let's look at the first rule called "comment". This rule says that if the COMMENT token exists, so if the regex returns a value, then save the token value ($0) as comment ($save_as_comment). So if you had comment lines (lines that start with a #, remember?) in the configuration file, BSA will save those.


The second rule called "record" says: If the LINE token exists then create a new field ($new_field) and give this field the value of token 0 ($0). Now this needs a bit of explanation. You can have multiple tokens in a rule and each of the tokens can have a value. Those values are number-indexed starting at 0. Think of it like an array of values. So the value assigned to the first token is value $0.


So again, the rule "record" says: If the token LINE exists (the regex return a value), then create a new field and give this field the value $0 of token LINE (LINE $new_field $0), then save record $0 and when you deploy this record, then apply add-rule $0 ($set_add_rule $0). As you can already see, we can also have multiple add-rules and add-rules are also indexed starting at $0.



The add-rules are used to describe what BSA needs to do when a record of this type is deployed using a BSA Deploy Job.

In our example the add-rule is called "add" and on deployment of this object BSA will write field $0 into the configuration file.


As you can see, writing grammars is not as mysterious as you might think. As a good practice exercise you can take a look at the example in the


I hope, the next time a customer wants you to manage a configuration file for which we don't have a grammar yet, you will write your own grammar and show your customer what BSA is capable of.


Ah, and once you have that grammar file, send it here so your colleagues will benefit from your efforts as well.


Have fun writing grammars!!