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.

clip_image001

 

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

clip_image003

 

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

clip_image004

 

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.

clip_image005

clip_image006

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. .

Comments on this Article
Comment made 15-Dec-2011 by Lalo_Calvillo 0
This is a very fast and effective way to change o redirect traffic througouth different nodes when a manual process is necessary.
Very useful.
0
Comment made 20-Aug-2014 by sprashanthac 70
I would like to know a way to merge the configuration on the V11.x GTM . Do we know of any merge examples
0
Comment made 20-Aug-2014 by sprashanthac 70
Never mind I think this will be helpful to others for version 11.x. in each case check the status tmsh load sys config merge gtm-only verify file eg. /var/tmp/file.txt tmsh load sys config merge gtm-only file eg. /var/tmp/file.txt
0
Comment made 16-Dec-2016 by brad 358

apparently, at least now in v12, there seems to be some sort of a whilte list / black list of where these files must reside in order to merge..

example: tmsh load sys config file myfile verify Data Input Error: The path "/home/xxx/myfile" is invalid. Check the valid paths with tmsh list sys global-settings file-whitelist-path-prefix file-blacklist-path-prefix file-blacklist-read-only-path-prefix

0