BIG-IP and Merge File Configuration Changes

Early in my exposure to F5 BIG-IP I was involved in a load balancer migration project from our existing hardware to F5 Load Balancers.  This involved the migration of several hundred configurations, so manual configuration of each new configuration was just not an option.

Direct modification of the configuration file (bigip.conf) was also not an option since it would require a “b load” command to activate any modifications, which is disruptive to active traffic during a reload.

A merge file on the other hand is non-service disrupting.  Meaning that the BIG-IP will not have to reload the entire configuration file and disrupt all other traffic in order to implement your change.  It will only make the changes that you specify.  If your change is disruptive (removing servers from a pool, putting up a maintenance pages or redirect, etc.) those changes will be disruptive for other reasons and not caused by the merge process.

The documentation of the command is pretty vague on usage, and it does not appear that very many people in the community are utilizing this feature which I have found immensely useful.

MERGE(1) BIG-IP Manual

NAME
     merge command - Loads the specified configuration file, which modifies the running configuration.

SYNTAX
     bigpipe merge (<file> | –)

DESCRIPTION
     The bigpipe merge command loads the specified configuration file or data. This modifies the running configuration. After you run the bigpipe merge command, if you want to save the modified running configuration in the stored configuration files, run the bigpipe save all command.

It is important to note that if you want to replace the running configuration of the BIG-IP system, rather than modify it, you use the bigpipe load command. For more information, see the man page for the bigpipe load command.

Merge files can be utilized to create or modify virtually anything that is contained within the bigip.conf configuration file (Virtual Servers, Pools, Nodes, iRules, Profiles, Classes, etc.). The basic structure of each can be found in the bigip.conf and copied to create a modification merge file (and a back-out merge file to restore the current configuration, so you can adhere to best practices and in compliance with most ITIL change management processes) or act as a template for a new configuration item.

Commands:

Merge file verification: bigpipe verify merge <file.name>

Merge specified file: bigpipe merge <file.name>

Implementation

I have a new set of Virtual Servers to implement, but none of the supporting pieces have been implemented yet.  Below is an example of the merge file followed by an attempted merge with the error that you will receive when verifying a merge file that has missing configurations or errors. The verify command will verify the syntax of the content and the existence of the items called in the merge file.

NOTE:  The top line of the Merge File specifies the target partition.  If you have implemented Administrative Domains and Partitions on your BIG-IP, this is where you will specify which partition to place things. You can implement multiple items in different partitions in the same merge file.  If you have not implemented Administrative Domains and Partitions you can specify the Common Partition.

NOTE:  The file extension (.txt) is not necessary.  These would actually be .tcl files if you wanted language recognition in an editor like Notepad++.

After merging the supporting configuration items the verification will return a good result:

Modification with Back-out

If you have a situation where a modification is necessary, you can retrieve the original (current) configuration from your bigip.conf and place it into a merge file(s).  I have discovered that it is a best practice to keep a copy of the original configuration for Back-Out purposes and a second copy to act as a template for a modification.

Merge files can also be change management friendly by allowing application configurations to be exported and kept in source control (and even versioned) with the application code providing a more holistic configuration repository or by attaching the configurations to whatever change management processes you may use.

Lastly, merge order matters….

The order that you plan to merge files will impact the success or failure of a group of merge files because of the configuration dependencies (Example:  You cannot merge a Virtual Server first if it is attempting to utilize a Pool that does not exist yet). 

I have discovered the following order:

• Classes (iRule Data Groups)
• Pools
• iRules
• Virtual Servers

Conclusion

• Merge file implementations are fast. Almost instant and implementations / modifications can be done on numerous items at a time.
• Non-service disruptive to other traffic or configurations
• Allows for pre-implementation verification
• Configurations can be exported and kept with an application in source control our used with change management processes

I hope that everyone finds this ability as useful as I have and that it makes your implementations easier. If anyone has any questions about the merge ability of bigpipe please join the Advanced Design and Configuration group on DevCentral and start a new thread in the forum. .