BigFix Actions

BigFix Actions allow a BigFix Console Operator to take virtually any action on BigFix Client computers. These actions can be embedded in custom content (Fixlets and Tasks) or can be used in custom actions. You can set the permissions of the BigFix Console users so they can be given custom content/action capabilities to send actions to BigFix Clients by using the BigFix Admin Tool.
Note: Custom content is not available in BigFix Standard Edition.

Using Custom Actions/Custom Content

To use custom actions:
  1. Open the BigFix Console and go to Tools > Take Custom Action (if the selection is grayed out then you do not have permission to use default actions).
  2. You will now be prompted with the Take Action dialog. The tabs are all the same as the normal Take Action dialog, except there are Action Script and Relevance Tabs.
  3. Fill in the Action Script with your custom action and use the other tabs to specify your action parameters (target computers, contraints, etc.).

To create custom content (for more information about authoring custom content, go to Custom Authoring):

  1. Open the BigFix Console and go to Tools > Create New Fixlet Message or Tools > Create New Task Message. Note that you can also right click on a Fixlet or Task and select "Create Custom Copy" to copy and then modify the fields from the Fixlet or Task. (If the selection is grayed out then you do not have permission to use default actions or you are using BigFix Standard Edition which does not include custom content capabilities).
  2. You will now be prompted with a Create Fixlet/Task Dialog.
  3. Fill in the requested tabs to create the custom content.
  4. Your Fixlet/Task will then appear in the Fixlet or Task tab. It will be stored in a Fixlet site with the same name as your user. If you do not see it appear in the relevant Fixlet/Task window within a few minutes, it probably means it is not relevant on any computers. You can uncheck View > Show Only Relevant Messages to make sure your Fixlet/Task was correctly created.

Embedding Relevance Expressions

The Windows action language has the ability to run embedded relevance expressions within the action. This adds significant power to the BigFix action language. Suppose you want to run an application that could be installed anywhere on a computer. If you had to hardwire a path, then it would be difficult to create an action that would work in all situations. However, if there was a registry value that contained the path to the application, you could use an embedded relevance expression to look up the value then run it. The resulting action might look like this:
  • run "{pathname of windows folder}\notepad.exe"
  • run "{pathname of parent folder of regapp "myapp.exe"}\myapp.exe"
  • run "{value "PathToEXE" of key "HKLM\Software\MyApp" of registry}"

Comment Characters

Action language will ignore all lines that start with //. This makes it easy to add comments to an action for reference. For example:

// Action to stop the Messenger service so that users do not receive
 // spam-like message pop-ups

dos net stop "Messenger"

Windows Action Reference

Following are a list of commonly used actions and some examples. For more details on all the possible actions, syntax, failure conditions, etc., please read the Windows Action Guide.

File Operations

Action language provides built-in file operation commands to allow quick simple operations.

Syntax

  • delete "<filename>"
  • move "<source filename>" "<destination filename>"
  • copy "<source filename>" "<destination filename>"
  • download <url>

Examples

  • copy "c:\testing\testfile.txt" "c:\testfile.txt"
  • copy "{pathname of system folder}\mshtml.dll" "C:\backupfiles\mshtml.dll"
  • move "d:\testfile.txt" "d:\temp\testfile.txt"
  • download http://download.microsoft.com/download/e/6/a/e6a04295-d2a8-40d0-a0c5-241bfecd095e/w2ksp4_en.exe
  • download http://besserver.companyname.com/downloadfolder/customapp.exe
  • download http://192.168.100.134:52311/download2/myapp.zip
  • delete "c:\testfile.txt"
  • delete "{pathname of windows folder}\virusfile.exe"

Notes

  • The delete command will fail if the file cannot be delete (this could happen if the file was READ-ONLY or if there was a permissions problem with the SYSTEM account), but the command will succeed if the file does not exist.
  • The copy and move command will fail if there is already a file name the same as the destination file.
  • The download command will put the file in the "__BESData\actionsite\__download" folder of the BigFix Client folder. (The default is "C:\Program Files\BigFix Enterprise\BigFix Client\__BESData\actionsite\__Download").
  • It is good practice to use quotes when deleting, copying, or moving a file.
  • Even though the download command specifies a url, the BigFix Client will receive all files through the BigFix Server and BigFix Relays (unless explicitly told to download from the Internet by specifying custom settings) as usual.

Registry Operations

Actions can also easily manipulate the registry by creating, changing, or deleting registry values.

Syntax

  • regset "<registry key>" "<value name>"=<value>
  • regdelete "<registry key>" "<value name>"

Examples

  • regset "[HKEY_LOCAL_MACHINE\Software\BigFix\TestKey]" "testValueName"="testValue"
  • regset "[HKEY_LOCAL_MACHINE\Software\OtherApp]" "TestDWORDValue"=dword:00000014
  • regset "[HKEY_LOCAL_MACHINE\Software\BigFix\TestKey]" "ActionTime"="{now}"
  • regset "[HKEY_LOCAL_MACHINE\SOFTWARE\OtherApp2\" "Path2exe"="c:\\program files\\otherapp\\otherapp.exe"
  • regset "[HKEY_LOCAL_MACHINE\SOFTWARE\OtherApp2\" "Path2exe"="{escapes of "c:\program files\otherapp\otherapp.exe"}"
  • regset "[HKEY_LOCAL_MACHINE\Software\BigFix\TestKey]" ""="This is the new default value."
  • regset "[HKEY_LOCAL_MACHINE\Software\BigFix\TestKey]" "ExampleBinaryValue"=hex:4d,49,4d,45,2d,56,6f,6e,3a,20,31,2e,30,0a,43
  • regdelete "[HKEY_LOCAL_MACHINE\Software\AnotherApp]" "ValueName"

Notes

  • The regset command will create the key and value if they do not already exist. If the value already exists, it will be overwritten.
  • The regset syntax obeys the same rules as the regedit program. If you would like to see an example of the syntax for any particular registry value, export a .reg file from regedit.exe and look at the file in a text editor.
  • The regset and regdelete syntax is very specific. Make sure to use the exact syntax as the examples above.
  • If the specified value name is blank ("") then the default value will be set.
  • Backslashes ("\") need to be escaped either by using the embedded relevance expression {escapes of "<string>"} or by manually escaping the backslashes ("\\"). See the examples above.
  • Regdelete does not delete registry keys. See the Windows Action Guide for more details on deleting a registry key.
  • Abbreviations of key names (i.e., HKLM, HKCU, HKU, etc. will not work in the registry actions; they will only work in the relevance expressions).
  • HKEY_CURRENT_USER values for the logged in user cannot be set because the BigFix Client runs as the SYSTEM account. You can set specific user valuse by using the HKEY_USERS registry branch.

Execution Operations

Actions can easily run files to provide almost limitless power.

Syntax

  • dos <dos command>
  • run "<full path to executable>" [<command-line options>]
  • wait "<full path to executable>" [<command-line options>]
  • script "<full path to script>"

Examples

  • dos cmd /c rd /q /s "C:\program files\kazaa"
  • dos net start MSSQL
  • dos net send MYCOMPUTER The version of the BESClient.exe is {version of regapp "BESClient.exe"}.
  • wait "C:\temp\download\setup.exe" /s
  • wait "{pathname of windows folder}\temp\341k3d\runmeandwait.exe"
  • run "{pathname of regapp "otherapp.exe"}"
  • run "C:\customapp\customapp.exe" /runquiet /opt2
  • script customscript.vbs

Notes

  • The dos command will create a dos window on the BigFix Client computer for the duration of the action.
  • Run and wait are equivalent commands except that run returns immediately and wait will wait for the application to exit.
  • It is good practice to always specify full paths to files because the commands to not necessarily have access to PATH information.
  • The script command will run visual basic and javascript files.
  • Some virus scanners will sometimes intercept visual basic scripts from running.
  • The default path of all actions is the "__BESData\actionsite" folder of the BigFix Client folder (default is "C:\Program Files\BigFix Enterprise\BigFix Client\__BESData\actionsite").
  • To run files that do not exist on the computer, use the download command to first download the file to the computer, then run the file.

Control Statements

Syntax

  • continue if <{relevance condition to evaluate}>
  • pause while <{relevance condition to evaluate}>

Examples

  • // download Windows 2000 SP4, verify the sha1 checksum and size, then run the service pack
    download http://download.microsoft.com/download/e/6/a/e6a04295-d2a8-40d0-a0c5-241bfecd095e/w2ksp4_en.exe
    continue if {(size of it = 135477136 and sha1 of it = "fadea6d94a014b039839fecc6e6a11c20afa4fa8") of file "w2ksp4_en.exe" of folder "__download"}
    wait __download/w2ksp4_en.exe -q -z -n -o
  • // uninstall myapp.exe, wait until it is uninstalled, then run installer (Note: if uninstaller fails, this action will wait indefinitely)
    continue if {exists regapp "myapp.exe"}
    run "C:\myappfiles\myapp-uninstaller.exe"
    pause while {exists regapp "myapp.exe"}
    wait "C:\myappfiles\myapp-installer.exe"

Note

  • Use caution when using the pause while command because if the relevance clause doesn't become false, the action will stay paused until the BigFix Client is restarted.

Other

Syntax

  • restart [<delay seconds>]
  • shutdown [<delay seconds>]
  • setting "[name]"="value" on "[effective date]" for client

Examples

  • shutdown 60
  • restart 30
  • shutdown
  • restart
  • // Restart before Jan 1, 2005
    restart {("Fri, 31 Dec 2004 23:59:00 -0000" as time - now) / second}
  • // Shutdown in 3 hours
    shutdown {(hour * 3) / second}
  • setting "Test Setting"="Test Value 1" on "{parameter "action issue date" of action}" for client
  • setting "_BESGather_Download_CacheLimitMB"="4096" on "Tue, 07 Jun 2006 08:10:17 +0000" for client

Notes

  • The restart and shutdown commands work the same way as the restart/shutdown options in the "Take Action" dialog in the BigFix Console.
  • Settings commands work the same way as if you were to create a setting using the "Edit Settings" dialog.
  • The "effective date" for settings commands controls how a BigFix Client handles settings actions. A BigFix Client will only set a settings value if the effective date is newer than the existing effective date. The effective date mechanism prevents older settings from overwriting newer settings (or you can specify dates manually to control the settings override behavior).

Unix/Linux Action Reference

On Unix/Linux computers with the BigFix Client, you can choose to run shell scripts or use the BigFix Action Language.

Shell Script

  • To run a shell script, make sure to choose sh as the Action Script Type in the Take Action dialog.
  • References on shell script for Linux/Unix are easily found on the Internet or in bookstores.
  • To run a specific shell interpreter, use #!/bin/sh or another interpreter as the first command in your action.
  • Most of the commands available in the Windows Action Reference can be used on Unix and Linux computers (i.e., download, move, copy, delete, etc.) if you choose to use the BigFix Action Script script type instead of the sh script type.
  • To combine commands from the BigFix Action Script script type and the sh script type, see the example below:
    // download a file
    download http://somesite.com/download/filetodownload

    // create a file with shell script commands using the "appendfile" action, for instance find a pattern in the file, then output a file with the results
    appendfile #!/bin/sh
    appendfile grep somepattern filetodownload | wc -l > outputfile

    // rename the script
    move __appendfile myscript

    // give permissions to run the script
    run chmod 777 myscript

    // run the script
    wait myscript