KACE Systems Management Appliance 14.1 Common Documents - KACE Service Desk Administrator Guide

TIP: The process of creating scripts is an iterative one. After creating a script, deploy it to a limited number of devices to verify that it runs as expected before deploying it to all managed devices. You can create a test label to do this verification. Enable scripts only after you have tested them.

Token replacement variables

Use token replacement values to add variables to scripts. The following list shows the token replacement values that can be used in the XML of scripts. At run time, these variables are replaced on the device with the appropriate values.

Table 28. Token replacement values
Item	Description
$(KACE_DEPENDENCY_DIR)	This is the folder where any script dependencies for this script are downloaded to the client. 5.2 or higher: $(KACE_DATA_DIR)\kbots_cache\packages\kbots\xxx 5.1: $(KACE_INSTALL)\packages\kbots\xxx
$(KACE_SYS_DIR) $(KBOX_SYS_DIR)	Agent device's system directory. Both are synonymous. Preferred: $(KACE_SYS_DIR). Windows: C:\Windows\System32 Mac OS X: / Linux: /
$(KACE_MAC_ADDRESS) $(MAC_ADDRESS) $(KBOX_MAC_ADDRESS)	Agent device's primary Ethernet MAC address. All are synonymous. Preferred: $(KACE_MAC_ADDRESS)
$(KACE_IP_ADDRESS) $(KBOX_IP_ADDRESS)	Agent's local IP address (corresponds with network entry of KACE_MAC_ADDRESS) (http://kace.kbox.com:80). Both are synonymous. Preferred: $(KACE_IP_ADDRESS)
$(KACE_SERVER_URL)	Combination of server, port, and URL prefix. (http://kace.kbox.com:80)
$(KACE_SERVER)	Hostname of appliance server. (kbox)
$(KACE_SERVER_PORT)	Port to use when connecting to the appliance server. (80/433)
$(KACE_SERVER_URLPREFIX)	Web protocol to use when connecting to the appliance server. (http/https)
$(KACE_COMPANY_NAME)	Agent's copy of the setting from server's config page.
$(KACE_KUID) $(KBOX_MACHINE_ID)	The unique Quest KACE ID assigned to this Agent. Both are synonymous. Preferred: $(KACE_KUID)
$(KACE_APP_DIR)	Installation directory for the Quest KACE Agent and plugins. For older Agents this is mapped to $(KACE_INSTALL). Windows: C:\Program Files\Quest\KACE\ or C:\Program Files (x86)\Quest\KACE\ Mac OS: /Library/Application Support/Quest/KACE/bin Linux: /opt/quest/kace/bin
$(KACE_DATA_DIR)	Installation directory for executables, scripts, packages, and so on. For older Agents this is mapped to $(KACE_INSTALL). Windows Vista and later: C:\ProgramData\Quest\KACE\ Mac OS: /Library/Application Support/Quest/KACE/data Linux: /var/quest/kace
$(KACE_AGENT_VERSION)	Substitutes the version number of the installed Agent. "5.2.12345". 5.2 or higher only.
$(KACE_AGENT_ARCH)	Substitutes the architecture of the installed Agent. "x86/x64". 5.2 or higher Windows only.
$(KACE_HARDWARE_ARCH)	Substitutes the architecture of the physical hardware. "x86/x64". 5.2 or higher Windows only.
$(KACE_OS_FAMILY)	Substitutes Windows, Mac, or Linux depending on the operating system of the Agent-managed device. 5.2 or higher only.
$(KACE_OS_ARCH)	Substitutes x86 or x64 depending on the installed version of Microsoft Windows. 5.2 or higher Windows only.

Add offline KScripts, online KScripts, or online shell scripts

You can add KScripts, specify the devices on which you want to run the scripts, and schedule scripts to run as needed.

Offline and online KScripts include one or more tasks. Within each Task section, there are Verify and Remediation sections where you can further define the script behavior. If a section is blank, it defaults to Success.

Go to the Script Detail page:

Log in to the appliance Administrator Console, https://appliance_hostname/admin. Or, if the Show organization menu in admin header option is enabled in the appliance General Settings, select an organization in the drop-down list in the top-right corner of the page next to the login information.

On the left navigation bar, click Scripting, then click Scripts.

Select Choose Action > New.

In the Configure tab, specify script settings:

Option

Description

Name

A meaningful name for the script that distinguishes it from others on the Scripts list.

Tip:	TIP: You can enable or disable one or more scripts on the Scripts page. To do that, select them in the table, click , then click Enable or Disable, as required.

Enabled

Whether the script is enabled to run on the target devices. Do not enable a script until you are finished editing and testing it and are ready to run it. Enable the script on a test label before you enable it on all devices.

Category

The script category. Choose an existing category from the drop-down list, or click New Category to add a category. If you do not to assign a category to this script, ensure this field is set to None.

Tip:

•

You can assign a category to one or more scripts on the Scripts page. To do that, select them in the table, click Choose Action > Category, then select a category in the list.

•

You can remove a category by assigning all scripts currently under a Category to None.

Type

The script type. Script types include:

•

Online KScripts: Scripts that run only when a target device is connected to the appliance. Online KScripts run at scheduled times based on the appliance clock. You can create these scripts using the scripting templates.

•

Offline KScripts: Scripts that run at a scheduled time, based on the target device’s clock. These scripts can run even when target devices are not connected to the appliance, such as when devices start up or when users log in. You can create these scripts using the scripting templates.

•

Online shell scripts: Scripts that run at scheduled times based on the appliance clock, but that run only when the target device is connected to the appliance. Online shell scripts are created using simple text-based scripts, such as Bash, Perl, batch, and so on, that are supported by the target device’s operating system. Batch files are supported on Windows, along with the different shell script formats supported by the specific operating system of the target devices. PowerShell scripts are also supported on Windows-based target devices.

Important:

IMPORTANT: You must ensure the proper file extension is associated with the script to enable it to run on the target OS. For example, you can run .sh scripts on Mac and Linux devices, and .ps1 PowerShell scripts on Windows devices.

Status

Whether the script is in development (Draft) or has been rolled out to your network (Production). Use the Template status if you are building a script to use as the basis for future scripts.

Description

(Optional) A brief description of the actions the script performs. This field helps you to distinguish one script from another on the Scripts list.

Notes

Any additional information you want to provide.

In the Deploy tab specify deployment options:

Option

Description

All Devices

Deploy to all devices. Clear the check box to limit the deployment to specific labels or devices.

Restrict to Labels

Limit deployment to devices that belong to specified labels. To select labels, click Edit, drag labels to the Limit Deployment to window, then click OK.

If you select a label that has a Replication Share or an alternate download location, the appliance copies digital assets from that Replication Share or alternate download location instead of downloading them directly from the appliance.

NOTE: The appliance uses a Replication Share before it uses the KACE Alt Location.

Devices

Limit deployment to one or more devices. To find devices, begin typing in the field.

Operating Systems

The operating systems on which the application runs. Applications are deployed only to devices with the selected operating systems.

Click Manage Operating Systems.

In the Operating Systems dialog box that appears, select the OS versions in the navigation tree, as applicable.

You have an option to select OS versions by their family, product, architecture, release ID, or build version. You can choose a specific build version, or a parent node, as needed. Selecting a parent node in the tree automatically selects the associated child nodes. This behavior allows you to select any future OS versions, as devices are added or upgraded in your managed environment. For example, to select all build current and future versions associated with the Windows 10 x64 architecture, under All > Windows > Windows 10, select x64.

Specify Windows Run As settings (for online shell scripts and KScripts that run on Windows devices only):

Option

Description

Local System

Run the script with administrative privileges on the local device. Use this setting for all scripts created with a template.

Logged-in user

Run the script as the user who is logged in to the local device. This affects the user’s profile.

All logged-in users

Run the script once for every user that is logged in to the device. This affects the profiles of all users.

Credentials

Run the Online Shell Script and KScripts in the context of credentials that are specified here. Select existing credentials from the drop-down list, or select Add new credential to add credentials not already listed.

See Add and edit User/Password credentials.

NOTE: When running online KScripts on Windows devices, message windows are not displayed on target devices when you select the option to run the script as a specific credentialed user. To display message windows, run the script as Local System, Logged-in user, or All logged-in users.

In the User Notify tab, specify user alert settings. Alerts are available only for online KScripts and online shell scripts on Windows and Mac devices running the KACE Agent version 5.1 and higher:

Option

Description

Notify User Before Run

Allow the user to run, cancel, or delay the action. This is especially important when reboots are required. If no user is logged in, the script runs immediately.

Options

Options presented to the user in the alert dialog (available when you select Alert user before run):

•

OK: Run immediately.

•

Cancel: Cancel until the next scheduled run.

•

Snooze: Prompt the user again after the Snooze Duration.

If the time specified in the Timeout elapses without a user response, the script runs at that time.

Interaction with Run As:

•

Only the console user can see the alert dialog, and therefore choose to Snooze or Cancel, regardless of the Run As setting.

•

Enabling an alert prompts the console user even if the script is set to run as all users or another user.

Timeout

The amount of time, in minutes, for the dialog to be displayed before an action is performed. If this time period elapses without the user pressing a button, the appliance performs the action specified in the Timeout drop-down list.

Timeout Action

The action to be performed when the Timeout period elapses without the user choosing an option.

Snooze Duration

The amount of time, in minutes, for the period after the user clicks Snooze. When this period elapses, the dialog appears again.

Initial Message

The message to be displayed to users before the action runs.

To customize the logo that appears in the dialog, see Configure appliance General Settings without the Organization component.

In the Schedule tab, specify run options:

Option

Description

None

Run in combination with an event rather than on a specific date or at a specific time.

Every n hours

Run at a specified interval.

Every day/specific day at HH:MM

Run daily at a specified time, or run on a designated day of the week at a specified time.

Run on the nth of every month/specific month at HH:MM

Run on the same day every month, or a specific month, at the specified time.

Run on the nth weekday of every month/specific month at HH:MM

Run on the specific weekday of every month, or a specific month, at the specified time.

Custom

Run according to a custom schedule.

Use standard 5-field cron format (extended cron format is not supported):

Use the following when specifying values:

•

Spaces ( ): Separate each field with a space.

•

Asterisks (*): Include the entire range of values in a field with an asterisk. For example, an asterisk in the hour field indicates every hour.

•

Commas (,): Separate multiple values in a field with a comma. For example, 0,6 in the day of the week field indicates Sunday and Saturday.

•

Hyphens (-): Indicate a range of values in a field with a hyphen. For example, 1-5 in the day of the week field is equivalent to 1,2,3,4,5, which indicates Monday through Friday.

•

Slashes (/): Specify the intervals at which to repeat an action with a slash. For example, */3 in the hour field is equivalent to 0,3,6,9,12,15,18,21. The asterisk (*) specifies every hour, but /3 restricts this to hours divisible by 3.

Examples:

•

15 * * * * Run 15 minutes after every hour every day

•

0 22 * * * Run at 22:00 every day

•

0 0 1 1,6 * Run at 00:00 on January 1 and June 1

•

30 8,12 * * 1-5 Run weekdays at 08:30 and 12:30

•

0 2 */2 * * Run every other day at 02:00

View Task Schedule

Click to view the task schedule. The Task Schedule dialog box displays a list of scheduled tasks. Click a task to review the task details. For more information, see View task schedules.

In the Schedule Options tab, select the applicable options.

Option

Description

Also run once at next device checkin (for offline KScripts only)

Runs the offline KScript once when new scripts are downloaded from the appliance.

Also Run before login (for offline KScripts only)

Runs the offline KScript when devices start up. This might cause devices to start up more slowly than normal.

NOTE: If a device has an Active Directory or Group Policy Object setting that displays a message that the user must acknowledge before logging on, scripts do not run until the message is acknowledged.

Also run once at next device checkin (for offline KScripts only)

Runs the offline KScript after users enter Windows login credentials.

Allow run while disconnected (for offline KScripts only)

Allows the offline KScript to run even if the target device cannot contact the appliance to report results. In such a case, results are stored on the device and uploaded to the appliance during the next connection.

Allow run without a logged-in user

Allows the script to run even if a user is not logged in. To run the script only when the user is logged in to the device, clear this option.

Run on next connection if offline

For online KScripts or Shell Scripts, this option enables the script to run on offline machines when they become online again.

When a script runs, it calculates the number of machines it is supposed to run on based on their labels, or their operating systems, or by manually identifying selected machines. Given that set of machines, the script then determines which of those machines are currently online, and then queues up a task for the online machines in the Konductor.

When you select this option, the script skips the step that identifies online machines and it runs on the online machines. For the offline machines, the task is added to the Konductor's queue, and it runs when those machine become online.

Any subsequent tasks for running the same script (for example, for an offline machine that already exists in the Konductor's queue) overwrite the existing tasks, so there can never be more than one task in the Konductor's queue for the same machine.

Having a high number of tasks in the Konductor may affect the appliance's performance, so the best practice is to use offline scripts for those machines that are typically offline, and only use this option with online scripts when the target machines are expected to be online, to avoid an overpopulating the Konductor's queue.

By default, this option is disabled.

To upload files required by the script:

In the Dependencies section, click Add new dependency.

Click Browse or Choose File.

Select a file, then click Open or Choose.

If a Replication Share is specified and enabled, the dependencies are downloaded from the specified Replication Share.

NOTE: If the Replication Share is inaccessible, the dependencies are downloaded from the appliance. To enable this setting, select the Failover To Appliance check box on the Replication Schedule Detail page. See Create Replication Shares.

Repeat this step to add dependencies as needed.

Online or Offline KScripts only. In the Tasks tab, click Add New Task to add a task.

The process flow of a task is a script similar to the following:

IF Verify THEN
Success
ELSE IF Remediation THEN
Remediation Success
ELSE
Remediation Failure

In the Policy or Job Rules section, specify the following settings for Task 1:

Option

Description

Attempts

Enter the number of times the appliance attempts to run the script.

If the script fails but remediation is successful, you might want to run the task again to confirm the remediation step. To do this, set the number of attempts to 2 or more. If the Verify section fails, the script runs the number of times specified in this field.

On Failure

•

Select Break to stop running upon failure.

•

Select Continue to perform remediation steps upon failure.

In the Verify section, click Add to add a step, then select one or more steps to perform.

See Adding steps to task sections of scripts.

In the On Success and Remediation sections, select one or more steps to perform.

See Adding steps to task sections of scripts.

In the On Remediation Success and On Remediation Failure sections, select one or more steps to perform.

See Adding steps to task sections of scripts.

Tip:

TIP: To remove a dependency, click the Delete button next to the item:

. This button appears when you mouse over an item.

TIP: Click the Edit button next to Policy or Job Rules to view the token replacement variables that can be used anywhere in the script:

. The variables are replaced at runtime with appropriate values.

TIP: See Token replacement variables.

10.

Online shell scripts only. In the Script section, specify the following settings:

Option

Description

Script Text

Type the script contents.

Script File Name

Enter the name and extension of the file that will contain the specified script.

Important:

Timeout (minutes)

Specify the maximum number of minutes the script can run on the target device.

Upload File

If the script creates a file, and you want to upload that file to the appliance, select this option, and provide the following information:

•

Upload File Name: Enter the name of the file.

•

Upload File Directory Path: Specify the directory where you want to store the file. If you want to use the default script directory (<appliance_installation_directory>/scripts), leave this field blank.

Delete Downloaded Files

If the script requires any other files to run, such as installers, and you want to delete them after the script execution, select this option.

11.

Do one of the following:

◦

Click Run Now to immediately push the script to all devices.

Use this option with caution. See Using the Run and Run Now commands.

◦

Click Save.

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

KACE Systems Management Appliance 14.1 Common Documents - KACE Service Desk Administrator Guide

About default scripts

About default scripts

Adding and editing scripts

Adding and editing scripts

Token replacement variables

Token replacement variables

Add offline KScripts, online KScripts, or online shell scripts

Add offline KScripts, online KScripts, or online shell scripts