Call for ideas / contributions for sample CLI scripts and usage examples

[jkh]

Hi folks,

As we are getting closer to being feature complete in the FreeNAS CLI (not quite there but close), we're trying to come up with some examples which show how to use the CLI in real-world scenarios as well as present little stand-alone code snippets which show how to use its advanced scripting features and otherwise educate administrators in how to bend FreeNAS to their will using the CLI.

Just as the Unix (Bourne) shell enabled an entire era of scripting the Unix operating system in ways that even its originators never imagined, we hope that the CLI will enable administrators to provision and control FreeNAS machines in ways hitherto not even possible, also using its remote connection and debugging abilities to control and interrogate multiple FreeNAS instances from a single client, whether FreeNAS itself or Linux, Windows or OS X desktop machines running the CLI (since the CLI is written primarily in Python, it is highly portable to any platform that supports a Python interpreter).

This is where we need your help and feedback. Specifically, we need ideas and contributions!

The very first examples we've been putting together are here, and right now they're fairly rudimentary as we're still casting around for good ideas of how to convey "what the CLI is good for" without getting so deep that the reader drowns in details without learning the syntax.

To be more specific, here is a very simple example from that directory:

Code:

function factorial(n) { if ( n <= 1) { return 1 }; return n*factorial(n-1) }

As you can see, it's a pretty straight-forward example. It shows you how to write a factorial function, which while not hugely useful on its own, at least demonstrates that:

1. The CLI can be extended with additional user-supplied functions.
2. It does basic arithmetic.
3. Yay, recursion! I remember that from CS class.

However, I think we can all agree that while illustrative of some very basic concepts, no admin is going to look at that example and say "Woo! That totally suggests some cool ways to use factorials in a NAS / app hosting product!" So let's look at a slightly longer example:

Code:

function user_input_routine(select_boot_env) {
     print("Do you want to delete ", select_boot_env["id"]);
     print("Enter show to print detailed info on the boot env.");
     return readline("Enter yes to delete, no (or any other key) to skip [show/yes/no]: ");
}

function delete_bootenvs() {
      bootenvs = $(/ boot environment show);
      print("Iterating through boot environments in ascending order w.r.t date created");
      delete_flag = "no";
      print("At any point hit q to quit this routine")
      print()
      while (delete_flag != "q" and length(bootenvs) != 0) {
              select_boot_env=shift(bootenvs);
              delete_flag= user_input_routine(select_boot_env);
              while (delete_flag == "show") {
                      print(select_boot_env);
                      delete_flag=user_input_routine(select_boot_env)
              }
              if (delete_flag == "yes") {
                      / boot environment ${select_boot_env["id"]} delete
              }
       }
}

delete_bootenvs();

That's obviously meatier and more interactive, and it does something most administrators could consider useful: It interactively loops through all your boot environments, from oldest to newest, and asks if you want to garbage-collect (delete) any of them, presumably to reclaim space on a boot pool which is starting to get uncomfortably full.

Most administrators can see an immediate need for this function, and will probably appreciate the fact that it doesn't just try to algorithmically decide which boot environments are still useful and which aren't ("old" doesn't necessarily equate to "first on the chopping block"), it leaves that decision in the admin's hands. Even so, that's a pretty deep example, and anyone not familiar with the CLI syntax is going to go "Whoa! There's a lot going on in that comparatively short snippet!" What do expressions in $()'s do? Is that an array de-reference in ${select_boot_env["id"]} or what, exactly??" and so on.

So, again, we're looking for ideas on how to make short-but-still-useful examples that will illustrate the various features of the CLI and allow the reader to slowly come up to speed on the many powerful features it provides, hopefully allowing admins to reach the point where they can confidently and productively start writing their own scripts to automate common tasks and even set up FreeNAS from start to finish without ever touching the GUI (not that the new GUI isn't going to be awesome but sometimes headless provisioning is very useful and powerful, particularly when you have to do it in bulk).

Those looking into this with us will also notice that FreeNAS (and the CLI) has grown in its feature set to support Virtual Machine and Docker Container hosting, so examples need not be limited just to managing storage. Examples which allow mass-provisioning of virtual machines or containerized applications are just as welcome, though we're still putting the finishing touches on the Docker container support so those examples may encounter some teething problems along the way (which is still fine - nothing gets a feature finished like people trying to use it ;)).

As an added bonus, anyone wishing to help out here will also be interacting directly with the team, so you'll be getting a head-start on learning the CLI for your troubles, as well as a lot of "on the job training" that will probably be in shorter supply after we go to BETA and are coping with a flood of folks coming through the doorway, as it were. If you want a chance to influence the CLI while it's still forming and learn a lot about its behaviors, this is the time! :)

Q. "Uhhhh. OK. That all sounds great. Specifically though, how and where can I help?"

A. "We have three principle ways of interacting with the project at an engineering level that you can choose from."

1. You can file your suggestion as a ticket at http://bugs.freenas.org (use the FreeNAS 10 tracker and the CLI ticket category).
2. You can submit an example directly at https://github.com/freenas/middleware in the form of a pull request (which we can comment on and refine as part of the submission process). Those will be especially welcome, as it's the easiest way for us to collaborate with you.
3. You can email (and/or join) the freenas-devel@lists.freenas.org mailing list if you'd like to discuss your idea or contribution a bit more interactively before taking things to the ticket filing / github pull request stage.

You can also use this Forum thread, of course, and I and others will do our best to keep up with it, though the other mechanisms above are still preferred as it allows the "general discussion" and "specific contributions" to be easily separated out and also provides tracking information for others to look at as the examples/ideas wind their way through the process pipeline on their way to being committed to the examples/ directory.

We're really proud of the way the CLI has been taking shape and hope you, the community, will join us in making it kick even more ass!