The Sun ZFS Storage 7000 appliance has a user friendly and easy to understand graphical web based interface we call
the "BUI" or "Browser User Interface".This interface is very useful for many tasks, but in some cases a script (or workflow) may be more appropriate, such as:Repetitive tasksTasks which work on (or obtain information about) a large number of shares or usersTasks which are triggered by an alert threshold (workflows)Tasks where you want a only very basic input, but a consistent output (workflows)The appliance scripting language is based on ECMAscript 3 (close to javascript). I'm not going to cover ECMAscript 3 in great depth (I'm far from an expert here), but I would like to show you some neat things you can do with
the appliance, to get you started based on what I have found from my own playing around.I'm making
the assumption you have some sort of programming background, and understand variables, arrays, functions to some extent - but of course if something is not clear, please let me know so I can fix it up or clarify it.Variable Declarations and ArraysVariablesECMAScript is a dynamically and weakly typed language. If you don't know what that means, google is your friend - but at a high level it means we can just declare variables with no specific type and on
the fly.For example, I can declare a variable and use it straight away in
the middle of my code, for example:projects=list();Which makes projects an array of values that are returned from
the list(); function (which is usable in most contexts). With this kind of variable, I can do things like:projects.length (this property on array tells you how many objects are in it, good for for loops etc). Alternatively, I could say:projects=3;and now projects is just a simple number.Should we declare variables like this so loosely? In my opinion,
the answer is no - I feel it is a better practice to declare variables you are going to use, before you use them - and given them an initial value. You can do so as follows:var myVariable=0;To demonstrate
the ability to just randomly assign and change
the type of variables, you can create a simple script at
the cli as follows (bold for input):fishy10:> script("." to run)> run("cd /");("." to run)> run ("shares");("." to run)> var projects;("." to run)> projects=list();("." to run)> printf("Number of projects is: %d\n",projects.length);("." to run)> projects=152;("." to run)> printf("Value of
the projects variable as an integer is now: %d\n",projects);("." to run)> .Number of projects is: 7Value of
the projects variable as an integer is now: 152You can also confirm this behaviour by checking
the typeof variable we are dealing with:fishy10:> script("." to run)> run("cd /");("." to run)> run ("shares");("." to run)> var projects;("." to run)> projects=list();("." to run)> printf("var projects is of type %s\n",typeof(projects));("." to run)> projects=152;("." to run)> printf("var projects is of type %s\n",typeof(projects));("." to run)> .var projects is of type objectvar projects is of type numberArraysSo you likely noticed that we have already touched on arrays, as
the list(); (in
the shares context) stored an array into
the 'projects' variable.But what if you want to declare your own array? Easy! This is very similar to Java and other languages, we just instantiate a brand new "Array" object using
the keyword new:var myArray = new Array();will create an array called "myArray".A quick example:fishy10:> script("." to run)> testArray = new Array();("." to run)> testArray[0]="This";("." to run)> testArray[1]="is";("." to run)> testArray[2]="just";("." to run)> testArray[3]="a";("." to run)> testArray[4]="test";("." to run)> for (i=0; i < testArray.length; i++)("." to run)> {("." to run)> printf("Array element %d is %s\n",i,testArray[i]);("." to run)> }("." to run)> .Array element 0 is ThisArray element 1 is isArray element 2 is justArray element 3 is aArray element 4 is testWorking With LoopsFor LoopFor loops are very similar to those you will see in C, java and several other languages. One of
the key differences here is, as you were made aware earlier, we can be a bit more sloppy with our variable declarations.
The general way you would likely use a for loop is as follows:for (variable; test-case; modifier for variable){}For example, you may wish to declare a variable i as 0; and a MAX_ITERATIONS variable to determine how many times this loop should repeat:var i=0;var MAX_ITERATIONS=10;And then, use this variable to be tested against some case existing (has i reached MAX_ITERATIONS? - if not, increment i using i++);for (i=0; i < MAX_ITERATIONS; i++){ // some work to do}So lets run something like this on
the appliance:fishy10:> script("." to run)> var i=0;("." to run)> var MAX_ITERATIONS=10;("." to run)> for (i=0; i < MAX_ITERATIONS; i++)("." to run)> {("." to run)> printf("
The number is %d\n",i);("." to run)> }("." to run)> .
The number is 0The number is 1The number is 2The number is 3The number is 4The number is 5The number is 6The number is 7The number is 8The number is 9While LoopWhile loops again are very similar to other languages, we loop "while" a condition is met. For example:fishy10:> script("." to run)> var isTen=false;("." to run)> var counter=0;("." to run)> while(isTen==false)("." to run)> {("." to run)> if (counter==10) ("." to run)> { ("." to run)> isTen=true; ("." to run)> } ("." to run)> printf("Counter is %d\n",counter);("." to run)> counter++; ("." to run)> }("." to run)> printf("Loop has ended and Counter is %d\n",counter);("." to run)> .Counter is 0Counter is 1Counter is 2Counter is 3Counter is 4Counter is 5Counter is 6Counter is 7Counter is 8Counter is 9Counter is 10Loop has ended and Counter is 11So what do we notice here? Something has actually gone wrong - counter will technically be 11 once
the loop completes... Why is this?Well, if we have a loop like this, where
the 'while' condition that will end
the loop may be set based on some other condition(s) existing (such as
the counter has reached 10) - we must ensure that we terminate this iteration of
the loop when
the condition is met - otherwise
the rest of
the code will be followed which may not be desirable. In other words, like in other languages, we will only ever check
the loop condition once we are ready to perform
the next iteration, so any other code after we set "isTen" to be true, will still be executed as we can see it was above.We can avoid this by adding a break into our loop once we know we have set
the condition - this will stop
the rest of
the logic being processed in this iteration (and as such, counter will not be incremented). So lets try that again:fishy10:> script("." to run)> var isTen=false;("." to run)> var counter=0;("." to run)> while(isTen==false)("." to run)> {("." to run)> if (counter==10) ("." to run)> { ("." to run)> isTen=true; ("." to run)> break;("." to run)> } ("." to run)> printf("Counter is %d\n",counter);("." to run)> counter++; ("." to run)> }("." to run)> printf("Loop has ended and Counter is %d\n", counter);("." to run)> .Counter is 0Counter is 1Counter is 2Counter is 3Counter is 4Counter is 5Counter is 6Counter is 7Counter is 8Counter is 9Loop has ended and Counter is 10Much better!Methods to Obtain and Manipulate DataGet MethodThe get method allows you to get simple properties from an object, for example a quota from a user.
The syntax is fairly simple:var myVariable=get('property');An example of where you may wish to use this, is when you are getting a bunch of information about a user (such as quota information when in a shares context):var users=list();for(k=0; k < users.length; k++){ user=users[k]; run('select ' + user); var username=get('name'); var usage=get('usage'); var quota=get('quota');...Which you can then use to your advantage - to print or manipulate infomation (you could change a user's information with a set method, based on
the information returned from
the get method).
The set method is explained next.Set MethodThe set method can be used in a simple manner, similar to get.
The syntax for set is:set('property','value'); // where value is a string, if it was a number, you don't need quotesFor example, we could set
the quota on a share as follows (first observing
the initial value):fishy10:shares default/test-geoff> script("." to run)> var currentQuota=get('quota');("." to run)> printf("Current Quota is: %s\n",currentQuota);("." to run)> set('quota','30G');("." to run)> run('commit');("." to run)> currentQuota=get('quota');("." to run)> printf("Current Quota is: %s\n",currentQuota);("." to run)> .Current Quota is: 0Current Quota is: 32212254720This shows us using both
the get and set methods as can be used in scripts, of course when only setting an individual share,
the above is overkill - it would be much easier to set it manually at
the cli using 'set quota=3G' and then 'commit'.List MethodThe list method can be very powerful, especially in more complex scripts which iterate over large amounts of data and manipulate it if so desired.
The general way you will use list is as follows:var myVar=list();Which will make "myVar" an array, containing all
the objects in
the relevant context (this could be a list of users, shares, projects, etc). You can then gather or manipulate data very easily.We could list all
the shares and mountpoints in a given project for example:fishy10:shares another-project> script("." to run)> var shares=list();("." to run)> for (i=0; i < shares.length; i++)("." to run)> {("." to run)> run('select ' + shares[i]);("." to run)> var mountpoint=get('mountpoint');("." to run)> printf("Share %s discovered, has mountpoint %s\n",shares[i],mountpoint);("." to run)> run('done');("." to run)> }("." to run)> .Share and-another discovered, has mountpoint /export/another-project/and-anotherShare another-share discovered, has mountpoint /export/another-project/another-shareShare bob discovered, has mountpoint /export/another-projectShare more-shares-for-all discovered, has mountpoint /export/another-project/more-shares-for-allShare yep discovered, has mountpoint /export/another-project/yepWriting More Complex and Re-Usable CodeFunctionsThe best way to be able to write more complex code is to use functions to split up repeatable or reusable sections of your code. This also makes your more complex code easier to read and understand for other programmers.We write functions as follows:function functionName(variable1,variable2,...,variableN){}For example, we could have a function that takes a project name as input, and lists shares for that project (assuming we're already in
the 'project' context - context is important!):function getShares(proj){ run('select ' + proj); shares=list(); printf("Project: %s\n", proj); for(j=0; j < shares.length; j++) { printf("Discovered share: %s\n",shares[i]); } run('done'); // exit selected project}Commenting your CodeLike any other language, a large part of making it readable and understandable is to comment it. You can use
the same comment style as in C and Java amongst other languages.In other words, sngle line comments use://at
the beginning of
the comment.Multi line comments use:/*at
the beginning, and:*/ at
the end.For example, here we will use both:fishy10:> script("." to run)> // This is a test comment("." to run)> printf("doing some work...\n");("." to run)> /* This is a multi-line("." to run)> comment which I will span across("." to run)> three lines in total */("." to run)> printf("doing some more work...\n");("." to run)> .doing some work...doing some more work...Your comments do not have to be on their own, they can begin (particularly with single line comments this is handy) at
the end of a statement, for examplevar projects=list(); //
The variable projects is an array containing all projects on
the system.Try and Catch StatementsYou may be used to using try and catch statements in other languages, and they can (and should) be utilised in your code to catch expected or unexpected error conditions, that you do NOT wish to stop your code from executing (if you do not catch these errors, your script will exit!):try{ // do some work}catch(err) // Catch any error that could occur{ // do something here under
the error condition}For example, you may wish to only execute some code if a context can be reached. If you can't perform certain actions under certain circumstances, that may be perfectly acceptable.For example if you want to test a condition that only makes sense when looking at a SMB/NFS share, but does not make sense when you hit an iscsi or FC LUN, you don't want to stop all processing of other shares you may not have covered yet.For example we may wish to obtain quota information on all shares for all users on a share (but this makes no sense for a LUN):function getShareQuota(shar) // Get quota for each user of this share{ run('select ' + shar); printf(" SHARE: %s\n", shar); try { run('users'); printf(" %20s %11s %11s %3s\n","Username","Usage(G)","Quota(G)","Quota(%)"); printf(" %20s %11s %11s %4s\n","--------","--------","--------","----"); users=list(); for(k=0; k < users.length; k++) { user=users[k]; getUserQuota(user); } run('done'); // exit user context } catch(err) { printf(" SKIPPING %s - This is NOT a NFS or CIFs share, not looking for users\n", shar); } run('done'); // done with this share}Running Scripts Remotely over SSHAs you have likely noticed, writing and running scripts for all but
the simplest jobs directly on
the appliance is not going to be a lot of fun.There's a couple of choices on what you can do here:Create scripts on a remote system and run them over sshCreate scripts, wrapping them in workflow code, so they are stored on
the appliance and can be triggered under certain circumstances (like a threshold being reached)We'll cover
the first one here, and then cover workflows later on (as these are for
the most part just scripts with some wrapper information around them).Creating a SSH Public/Private SSH Key PairLog on to your handy Solaris box (You wouldn't be using any other OS, right? :P) and use ssh-keygen to create a pair of ssh keys. I'm storing this separate to my normal key:[geoff@lightning ~] ssh-keygen -t rsa -b 1024Generating public/private rsa key pair.Enter file in which to save
the key (/export/home/geoff/.ssh/id_rsa): /export/home/geoff/.ssh/nas_key_rsaEnter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /export/home/geoff/.ssh/nas_key_rsa.Your public key has been saved in /export/home/geoff/.ssh/nas_key_rsa.pub.
The key fingerprint is:7f:3d:53:f0:2a:5e:8b:2d:94:2a:55:77:66:5c:9b:14 geoff@lightningInstalling
the Public Key on
the ApplianceOn your Solaris host, observe
the public key:[geoff@lightning ~]
cat .ssh/nas_key_rsa.pub ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAvYfK3RIaAYmMHBOvyhKM41NaSmcgUMC3igPN5gUKJQvSnYmjuWG6CBr1CkF5UcDji7v19jG3qAD5lAMFn+L0CxgRr8TNaAU+hA4/tpAGkjm+dKYSyJgEdMIURweyyfUFXoerweR8AWW5xlovGKEWZTAfvJX9Zqvh8oMQ5UJLUUc= geoff@lightningNow, copy and paste everything after "ssh-rsa" and before "user@hostname" - in this case, geoff@lightning. That is, this bit:AAAAB3NzaC1yc2EAAAABIwAAAIEAvYfK3RIaAYmMHBOvyhKM41NaSmcgUMC3igPN5gUKJQvSnYmjuWG6CBr1CkF5UcDji7v19jG3qAD5lAMFn+L0CxgRr8TNaAU+hA4/tpAGkjm+dKYSyJgEdMIURweyyfUFXoerweR8AWW5xlovGKEWZTAfvJX9Zqvh8oMQ5UJLUUc=Logon to your appliance and get into
the preferences -> keys area for this user (root):[geoff@lightning ~] ssh
[email protected]: Last login: Mon Dec 6 17:13:28 2010 from 192.168.0.2fishy10:> configuration usersfishy10:configuration users> select rootfishy10:configuration users root> preferences fishy10:configuration users root preferences> keysOR do it all in one hit:fishy10:> configuration users select root preferences keysNow, we create a new public key that will be accepted for this user and set
the type to RSA:fishy10:configuration users root preferences keys> createfishy10:configuration users root preferences key (uncommitted)> set type=RSASet
the key itself using
the string copied previously (between ssh-rsa and user@host), and set
the key ensuring you put double quotes around it (eg. set key="<key>"):fishy10:configuration users root preferences key (uncommitted)> set key="AAAAB3NzaC1yc2EAAAABIwAAAIEAvYfK3RIaAYmMHBOvyhKM41NaSmcgUMC3igPN5gUKJQvSnYmjuWG6CBr1CkF5UcDji7v19jG3qAD5lAMFn+L0CxgRr8TNaAU+hA4/tpAGkjm+dKYSyJgEdMIURweyyfUFXoerweR8AWW5xlovGKEWZTAfvJX9Zqvh8oMQ5UJLUUc="Now set
the comment for this key (do not use spaces):fishy10:configuration users root preferences key (uncommitted)> set comment="LightningRSAKey" Commit
the new key:fishy10:configuration users root preferences key (uncommitted)> commitVerify
the key is there:fishy10:configuration users root preferences keys> lsKeys:NAME MODIFIED TYPE COMMENT key-000 2010-10-25 20:56:42 RSA cycloneRSAKey key-001 2010-12-6 17:44:53 RSA LightningRSAKey As you can see, we now have my new key, and a previous key I have created on this appliance.Running your Script over SSH from a Remote SystemHere I have created a basic test script, and saved it as test.ecma3:[geoff@lightning ~]
cat test.ecma3 script// This is a test script, By Geoff Ongley 2010.printf("Testing script remotely over ssh\n");.Now, we can run this script remotely with our keyless login:[geoff@lightning ~] ssh -i .ssh/nas_key_rsa root@fishy10 < test.ecma3Pseudo-terminal will not be allocated because stdin is not a terminal.Testing script remotely over sshPutting it Together - An Example Completed Quota Gathering ScriptSo now we have a lot of
the basics to creating a script, let us do something useful, like, find out how much every user is using, on every share on
the system (you will recognise some of
the code from my previous examples):
script/************************************** Quick and Dirty Quota Check script ** Written By Geoff Ongley ** 25 October 2010 **************************************/function getUserQuota(usr){ run('select ' + usr); var username=get('name'); var usage=get('usage'); var quota=get('quota'); var usage_g=usage / 1073741824; // convert bytes to gigabytes var quota_g=quota / 1073741824; // as above var quota_percent=0 if (quota > 0) { quota_percent=(usage / quota)*(100/1); } printf(" %20s %8.2f %8.2f %d%%\n",username,usage_g,quota_g,quota_percent); run('done'); // done with this selected user}function getShareQuota(shar){ //printf("DEBUG: selecting share %s\n", shar); run('select ' + shar); printf(" SHARE: %s\n", shar); try { run('users'); printf(" %20s %11s %11s %3s\n","Username","Usage(G)","Quota(G)","Quota(%)"); printf(" %20s %11s %11s %4s\n","--------","--------","--------","--------"); users=list(); for(k=0; k < users.length; k++) { user=users[k]; getUserQuota(user); } run('done'); // exit user context } catch(err) { printf(" SKIPPING %s - This is NOT a NFS or CIFs share, not looking for users\n", shar); } run('done'); // done with this share}function getShares(proj){ //printf("DEBUG: selecting project %s\n",proj); run('select ' + proj); shares=list(); printf("Project: %s\n", proj); for(j=0; j < shares.length; j++) { share=shares[j]; getShareQuota(share); } run('done'); // exit selected project}function getProjects(){ run('cd /'); run('shares'); projects=list(); for (i=0; i < projects.length; i++) { var project=projects[i]; getShares(project); } run('done'); // exit context for all projects}getProjects();.Which can be run as follows, and will print information like this:[geoff@lightning ~/FISHWORKS_SCRIPTS] ssh -i ~/.ssh/nas_key_rsa root@fishy10 < get_quota_utilisation.ecma3Pseudo-terminal will not be allocated because stdin is not a terminal.Project: another-project SHARE: and-another Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- nobody 0.00 0.00 0% geoffro 0.05 0.00 0% Billy 0.10 0.00 0% root 0.00 0.00 0% testing-user 0.05 0.00 0% SHARE: another-share Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- root 0.00 0.00 0% nobody 0.00 0.00 0% geoffro 0.05 0.49 9% testing-user 0.05 0.02 249% Billy 0.10 0.29 33% SHARE: bob Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- nobody 0.00 0.00 0% root 0.00 0.00 0% SHARE: more-shares-for-all Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- Billy 0.10 0.00 0% testing-user 0.05 0.00 0% nobody 0.00 0.00 0% root 0.00 0.00 0% geoffro 0.05 0.00 0% SHARE: yep Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- root 0.00 0.00 0% nobody 0.00 0.00 0% Billy 0.10 0.01 999% testing-user 0.05 0.49 9% geoffro 0.05 0.00 0%Project: default SHARE: Test-LUN SKIPPING Test-LUN - This is NOT a NFS or CIFs share, not looking for users SHARE: test-geoff Username Usage(G) Quota(G) Quota(%) -------- -------- -------- -------- geoffro 0.05 0.00 0% root 3.18 10.00 31% uucp 0.00 0.00 0% nobody 0.59 0.49 119%^CKilled by signal 2.Creating a WorkflowWorkflows are scripts that we store on
the appliance, and can have
the script execute either on request (even from
the BUI), or on an event such as a threshold being met.Workflow BasicsA workflow allows you to create a simple process that can be executed either via
the BUI interface interactively, or by an alert being raised (for some threshold being reached, for example).
The basics parameters you will have to set for your "workflow object" (notice you're creating a variable, that embodies ECMAScript) are as follows (parameters is optional):name: A name for this workflowdescription: A Description for
the workflowparameters: A set of input parameters (useful when you need user input to execute
the workflow)execute: The code,
the script itself to execute, which will be function (parameters)With parameters, you can specify things like this (slightly modified sample taken from
the System Administration Guide): ...parameters: variableParam1: { label: 'Name of Share', type: 'String' }, variableParam2 { label: 'Share Size', type: 'size' },execute: ....}; Note
the commas separating
the sections of name, parameters, execute, and so on. This is important!Also - there is plenty of properties you can set on
the parameters for your workflow, these are described in
the Sun ZFS Storage System Administration Guide.Creating a Basic Workflow from a Basic ScriptTo make a basic script into a basic workflow, you need to wrap
the following around your script to create a 'workflow' object:var workflow = {name: 'Get User Quotas',description: 'Displays Quota Utilisation for each user on each share',execute: function() {// (basic script goes here, minus
the "script" at
the beginning, and "." at
the end)}};However, it appears (at least in my experience to date) that
the workflow object may only be happy with one function in
the execute parameter - either that or I'm doing something wrong. As far as I can tell, after execute: you should only have a basic one function context like so:execute: function(){}To deal with this, and to give an example similar to our script earlier, I have created another simple quota check, to show
the same basic functionality, but in a workflow format:var workflow = {name: 'Get User Quotas',description: 'Displays Quota Utilisation for each user on each share',execute: function () { run('cd /'); run('shares'); projects=list(); for (i=0; i < projects.length; i++) { run('select ' + projects[i]); shares=list('filesystem'); printf("Project: %s\n", projects[i]); for(j=0; j < shares.length; j++) { run('select ' +shares[j]); try { run('users'); printf(" SHARE: %s\n", shares[j]); printf(" %20s %11s %11s %3s\n","Username","Usage(G)","Quota(G)","Quota(%)"); printf(" %20s %11s %11s %4s\n","--------","--------","--------","-------"); users=list(); for(k=0; k < users.length; k++) { run('select ' + users[k]); username=get('name'); usage=get('usage'); quota=get('quota'); usage_g=usage / 1073741824; // convert bytes to gigabytes quota_g=quota / 1073741824; // as above quota_percent=0 if (quota > 0) { quota_percent=(usage / quota)*(100/1); } printf(" %20s %8.2f %8.2f %d%%\n",username,usage_g,quota_g,quota_percent); run('done'); } run('done'); // exit user context } catch(err) { // printf(" %s is a LUN, Not looking for users\n", shares[j]); } run('done'); // exit selected share context } run('done'); // exit project context } }};SummaryThe Sun ZFS Storage 7000 Appliance offers lots of different and interesting features to Sun/Oracle customers, including
the world renowned Analytics. Hopefully
the above will help you to think of new creative things you could be doing by taking advantage of one of
the other neat features,
the internal scripting engine!Some references are below to help you continue learning more, I'll update this post as I do
the same! Enjoy...More information on ECMAScript 3A complete reference to ECMAScript 3 which will help you learn more of
the details you may be interested in, can be found here:http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdfMore Information on Administering
the Sun ZFS Storage 7000The Sun ZFS Storage 7000 System Administration guide can be a useful reference point, and can be found here:http://wikis.sun.com/download/attachments/186238602/2010_Q3_2_ADMIN.pdf
