Getting Started with iApps: Creating an iApp

In the previous article in this series, we took a stock iApp shipped with the product and stripped it down to show how to modify an existing iApp. In this article, we’ll tackle creating a simple iApp from scratch.

The Scenario

You have a test environment where all your iRules are created and validated. You then send them off to other devices in test or stage environments, and finally, production. Wouldn’t it be nice to have a quick validation that the rules out there in the other environments match the ones in yours? This is possible by adding a checksum or signature to your iRules. You can do this in the GUI of course, and with checksums, you can do it all at the same time by checking all the iRules and clicking the Add Checksum box.

Now in list view, you’ll see that the verification has changed from None to Checksum Verified.

If you click into one of the iRules, you’ll see the checksum definition at the end of the iRule (I know, lamest “test” iRule ever!)

If you want to add signatures to all iRules simultaneously like you can with checksums though, well that doesn’t work.

It is this very situation that we will attempt to solve with an iApp!

The tmsh Underbelly

Before beginning the iApp, let’s figure out what we actually need to do in tmsh since the implementation section will rely on this. For this iApp, it’s pretty simple. Take a list of iRules, and generate a signature or checksum. The tmsh commands are thus:

# Generate a signature
tmsh generate ltm rule  signature signing-key 
# Generate a checksum
tmsh generate ltm rule  checksum

So in the presentation section, we’re going to need to provide for the following to pass to the implementation:

1. Determine if they want to generate a checksum or a signature
2. If a signature, display a list of keys they can select a single key from for signing
3. Display a list of iRules they can select one or more from

Creating the Presentation Section

If you recall from the previous articles in this series, the presentation section of the template is created with the APL language. Within the presentation, there is an area where your inputs are defined, and then an area where the text supporting those inputs are defined.

section basic_info {
  choice validation default "Checksum" { "Checksum", "Signature" }
  optional (validation == "Signature") {
    choice key tcl {
      set objs [tmsh::get_config /sys crypto key]
      foreach obj $objs {
        append results [tmsh::get_name $obj]
        append results "\n"
      }
      return $results
    }
  }
  multichoice rules tcl {
    set objs [tmsh::get_config /ltm rule]
    foreach obj $objs {
      append results [tmsh::get_name $obj]
      append results "\n"
    }
    return $results
  }
}
text {
  basic_info "Add Signature or Checksum to iRules"
  basic_info.validation "Please select Signature or Checksum."
  basic_info.key "Please select the key for iRule signature."
  basic_info.rules "Please select one or more iRules."
}

First thing we’ll do is title the section basic_info (lines 1-21.) The first choice we’ll present, which we’ll name validation, is whether the user would like to apply a checksum or a signature to the iRules (line 2.) If that choice is a signature, we’ll run a tcl function to retrieve all the crypto keys on the system to present that in a choice object (lines 3-11,) storing those values in key. Next, we want to be able to select more than one iRule from the list, so we’ll use a multichoice instead of just a choice object. We’ll run a similar tcl function to retrieve the iRule names for display (lines 13-20,) storing those values in rules.

In the text section (lines 22-27) we use the names from above to apply the helper text to those objects. Each object within the section gets a name of section.object, so for the information that we have so far, that results in:

• basic_info (line 23) -> section basic_info (line 1)
• basic_info.validation (line 24) -> section basic_info choice validation (line 2)
• basic_info.key (line 25) -> section basic_info choice key (line 4)
• basic_info.rules (line 26) -> section basic_info multichoice rules (line 13)

That’s it! With the presentation section of the template complete, we can move on to implementation.

Creating the Implementation Section

For (most?) iApps, the presentation is the easy part. But that is not the case in this iApp. This implementation code is 12 lines long including braces, and it’s a single switch statement. Before we get to the code, however, a few points:

1. To reference names from the presentations so you can retrieve the values you set, the format is $::section__objName. So for basic_info.validation, the variable name is $::basic_info__validation. Don’t let that double colon or the double underscore throw you.
2. If you are including the built-in iApps packages, there are newer iapp:: namespace commands that you can use for configuration and for retrieval. Rather than confuse the functionality of what the iApp is actually doing, I left that out of this article, but as you begin developing iApps, you’ll want to use the package.
3. The generate command in tmsh does not have a scripting sibling, so rather than using tmsh::generate (which does not exist,) you need to use the exec command.

switch -exact $::basic_info__validation {
"Checksum" {
foreach obj $::basic_info__rules {
exec "tmsh" "generate" "ltm" "rule" $obj "checksum"
}
}
"Signature" {
foreach obj $::basic_info__rules {
exec "tmsh" "generate" "ltm" "rule" $obj "signature" "signing-key" $::basic_info__key
}
}
}

As you can see from the code, a single switch statement (line 1) checks to see whether it matches Checksum (line 2) or Signature (line 7.) Given a match, it will loop through the iRules (lines 3, 8) and then run the tmsh command to add the Checksum (line 4) or the Signature (line.)

Creating the Help Section

This is the section where I punt. It’s just html, and I think we can all agree that is out of the scope of this article.

Creating the iApp Template

Now that we have our sections complete, we can actually create the iApp.

1. Go to iApps->Templates and click Create.
2. Give the template a name. I named mine f5.add_irules_validation.
3. Set the required BIG-IP Modules field to LTM.
4. I haven’t tested this iApp on other versions, so I’ll be picky and set the minimum version to my test VE’s 12.1 version and leave the maximum blank.
5. I haven’t used a macro, so I’ll leave that alone.
6. Paste the implementation into that section.
7. Paste the presentation into that section.
8. Ignore the HTML Help. (A quick aside…my robotics students will have a field day if they find out I didn’t document here. Shhhhh…)
9. Click Finish

Creating the Application Service

Final steps! Now we can create the application service. The original scenario described our problem: we want to apply a signature to all the iRules at once. So let’s do that.

1. Go to iApps->Application Services and click Create.
2. Name it. I named mine add_irules_signatures.
3. Select the Template from the list.
4. Select Signature
5. Select the appropriate key. I selected the default.
6. Select the appropriate iRules. I selected test1 and test2.
7. Click Finish.

Before clicking Finish, my application service looked like this:

No errors locally. Whew! The components view is not too exciting:

The reason for this is the iApp doesn’t own any components. It just acted on existing components, so there is nothing for it to own. However, we can see the results of its action by going to the iRules section to see if the verification column on test1 and test2 has changed from None (caveat…I did remove the checksums from earlier, you can’t apply a checksum and a signature, it’s one or the other.) Low and behold, we have signatures now!

Conclusion

This article covered the steps required to get to a functional template for deploying an application service. As demonstrated, iApps don’t necessarily have to be a configuration engine, they can be used for other purposes. The steps were purposefully kept very simple and uncluttered to make all the pieces clear. Obviously, iApps can get very complex and there are some best practices and lessons learned that we’ll cover in the next article in this series.