v.10 Introduction to the tmsh Command Shell

While bigpipe, the primary command processor for tmos prior to version 10.0 was useful, growth of the product and addition of both new hardware and software modules was starting to stretch the limits of that fine interface. Looking forward, our smart Product Development people set out to write a command processor that would carry us forward from version 10 with more cohesion.

And the result is the ultra-powerful tmsh. While you can still call bigpipe, I strongly suspect that in a short amount of time you won’t be bothering. tmsh unifies all the different bits of the BIG-IP product line into one easy-to-use command line. In fact, it is so powerful and easy to use that I suspect you will be replacing some functionality that you have traditionally placed in iControl with tmsh scripts. But more on that a little later in the article, first let’s look at what it’s all about.

The design is simple, there is a tree-like hierarchy that grows as you add modules to your BIG-IP, with tmsh root at the top, and each module/sub-module accessible in a directory structure much like a file system. Utilizing file-system style command paths you can execute a tmsh command in any module from anywhere in the command tree, or you can change to the specific module and just use the name.

The commands are all formatted the same, and consist of the following:

Where action is what to do – create, delete, list, etc. Location is where in the directory tree the type is located (and can be left off if it’s in your current location), ItemName is the object to work on – the name of the pool, virtual, whatever, and the parameters are any extra items the specific command needs.

Add to this universal access and expandable nature the ability to save scripts for re-execution, and you have a powerful tool at your disposal to handle management tasks. Need to quickly move members into and out of a pool? Write a script to handle it, and just execute on-demand. Need to point a VIP at a different pool so you can upgrade the systems in the current pool? Again, write a script, since you’ll be doing it again.

I’ll steal (and generalize) one of the examples from the excellent tmsh Reference Guide (ask.f5.com login required) that our technical publications people have produced to show you what I mean. From anywhere in the hierarchy, you can execute the simple command

And it does. You can imagine that combining this with other commands can put you into a command line automation nirvana.

And then we get to talk about the expandability part. Add a module – let’s say you added Global Traffic Manager (gtm) to your BIG-IP to load balance between your data centers. Once you’ve installed and licensed GTM, the commands in the gtm module all become available in tmsh. It’s that easy.

So why do I think that you might replace some functionality that you have traditionally used iControl for with tmsh scripts? Well, a lot of the functionality of iControl is for use in managing your BIG-IPs, but what if you could put scripts on the BIG-IP and just go out to execute them? No need to learn a programming language or write a ton of supporting code, just generate the required script and save it to the disk of the BIG-IP? Yeah, the overhead of iControl, while necessary to make it run from anywhere, is large enough that if you have functionality you don’t need to be able to run from any machine, you’ll likely turn to tmsh. And that alone is enough reason for it to have come into being – saving you time.

But that’s all just the tip of the iceberg, because you see, tmsh has built-in transaction support. Yep, do it all or do nothing style. And it will let you load and save configs, so you can modify a configuration, save it to a different name, and use that for testing. All in a script.

And it’s not all about scripting, you can use the tmsh edit command to edit an iRule. Yeah, right there, in a text editor. Nifty.

Note that it is a complex system that you are manipulating, and the tmsh designers wanted to give you the most possible options, so things like Create Virtual are not simple commands if you want to generate a working Virtual. There’s a lot that a Virtual needs to know, so you’ll likely use create to create it and modify to set all of the various parameters. But it is likely that we here at DevCentral (that includes you!) will be generating a lot of scripts to group commonly used functionality together into a single “command”.

Another bit of good news is that the scripting language is tcl, so you can utilize functionality available in tcl in your commands. Variable declaration, parameter processing, looping and decision constructs are all available to you to make your scripts more powerful.

So as I mentioned above, I suspect you will have a list of regular maintenance items that you perform and have in the past gone to the BIG-IP UI to do step-by-step or have an iControl program to execute, that you will be running in tmsh going forward – because you can write a script and tell tmsh to execute it.

One thing the tmsh Reference Guide doesn’t have in it (but you can find in the man pages on the BIG-IP in v.10), is how to create and work with tmsh scripts. So we’ll cover it here, just to give you a feel. The man pages are the definitive source for this information of course, but I’ll cover the basics for you.

From the tmos command prompt if you type edit cli command-script name, it will open an editor for that file name. If the file exists it will load it, if the file does not exist, it will give you a blank window in which to create.

If, from the tmos command prompt you type run cli command-script name, it will behave exactly as expected. Note that within the script, parameters passed on the command line are available with the tmsh::argc and tmsh::argv parameters. Yeah, I have a whole list of ideas about what to do with that feature in regards to automation.

Some of the cool “oh yeah” functions available are command completion – on the command line tab-completion of tmsh commands is available, history in the same sense as Unix/Linux bash_history, context sensitive help – end a command with ? and it will list the options available from the question mark on, grep for output filtering, and the already mentioned (but worth mentioning again) transaction support.

I expect that our upcoming tmsh CodeShare area will be filled with useful little scripts relatively quickly, just because the Product Development folks made it so easy to do. We like to generate automation tools, in case you missed it, and tmsh is automation in a can. I don’t yet see a way to execute a script from within a script, but if that’s all they missed, we’ll work it out with common subroutines that you can cut-n-paste.

One thing that I found intriguing but haven’t exactly figured out how I’ll use it yet – or perhaps by the time this is posted I will have – is that you can use tmsh::system::log to dump the logs, and grep to filter them, and have them accessible inside tmsh. Hmmm… There are a lot of uses for that, have to pick one and do some serious thought about how to utilize it. I sense an upcoming Tech Tip, that’s for certain!

Finally, I’ll leave you with a feel for how complete the coverage of tmsh is. I won’t go into detail here, the tmsh Reference Guide has a more than complete description and reference for each of the modules listed below.

• Global – Global functionality relative to tmsh
• Auth – Authentication commands and objects
• Cli – commands relative to the TMOS command line interface
• Gtm – three modules for gtm, monitoring, and settings
• Ltm – four modules for ltm, profiles, monitors, and persistence
• Net – three modules for the network, rate shaping, and tunnels
• Sys – two modules, one for system, one for system performance

One thing that doesn’t seem to be present is the iControl locking mechanism, but since there is a complete transaction processing system, I suppose that this makes perfect sense. The purpose of locks is to assure that your changes go through, the purpose of a transaction is to… make certain your changes go through. There are a few things you can do with locking that transactions won’t do, but those are few, and iControl isn’t going away, so if you need to do something like determine who else is trying to update while you are, you can fall back to iControl to handle it.

As you can see, there’s a wealth of programmatic access built into the system, and we’ll no doubt be gearing up DevCentral to help you take full advantage of tmsh. In the end it is another powerful tool in your systems management toolbox, and I’m excited about digging in and bringing you some kicking examples to get you started over the coming months.