You can run JumpCloud commands to execute scripts on fleets of machines through JumpCloud's agent. You can deploy files, schedule maintenance activity, or install software on endpoints in PowerShell, Bash, Shell, and more. Commands can run across one or more devices in parallel and retrieve command results, including stdout, stderr, and exit codes.
Commands let you quickly and easily automate tasks across multiple servers, launch those tasks based on a number of different types of events, and get full auditing of all command results. Several standard commands are already available to you. You can also create new commands manually or from a command template. Using an existing command template to create a command helps you quickly and efficiently update your devices.
From the Commands page, you can quickly run or delete a command.
Considerations:
- JumpCloud uses the Windows NT\Authority System account to run commands on remote systems, preventing the use of commands that require a user context to run.
- To run a command with user context, such as making changes to the HKEY_CURRENT_USER registry hive to implement a custom group policy, use one of the custom command templates titled, “Windows – Run As Signed In User Template | v1.1 JCCG”.
- The execution time for scheduled and repeating launch events corresponds with the target system’s time zone.
- The time shown in the Results tab takes the current time on the system where the command is run, and then converts it to UTC.
- When running commands for macOS, you might get a result code of 1 with a log message of Operation Not Permitted. This might indicate that the JumpCloud agent needs Full Disk Access permissions to successfully run the command. See Grant Full Disk Access Permissions to the JumpCloud Agent for MacOS.
Prerequisites:
- You need a managed device running on a supported OS to create a command.
- You need to create device groups before you create a command. See Create a Device Group.
Creating a Command Manually
A manual command is run once and the Time To Live setting controls the queue timeout based on your requirements.
To create a new command manually:
- Log in to the JumpCloud Admin Portal.
- Go to DEVICE MANAGEMENT > Commands.
- Click ( + ), then choose Command.
- On the Details tab, enter a name for the new command. This is the name shown in the sortable list view of commands.
- For Type, select Linux, Windows, or Mac.
- Linux: Select the Run As user account that will run the command.
- Windows: Commands will be run as the LocalSystem account and optionally can be run as PowerShell.
- Mac: Select the Run As user account that will run the command.
- For Command, type or paste a script. The script can be in any language that your servers can execute.
- For Event, choose a method to launch the command:
- Run Manually – Execute this command from the Commands tab. To quickly execute a command manually, click Run Now next to the command’s name in the Commands page.
- Run as Scheduled: Execute this command one time on the day and time that you specify in Schedule run for. This setting is useful for one-time operations that need to run during a change window. For more detail, see Understanding Scheduled Commands below.
- Run as Repeating: Execute this command on the interval you specify:
- Command Repeats By: Specify when the command should repeat. You can select that it repeat by a specific Minute/Hour/Day/Week/Month.
- Repeat Every: Specify the number of days after which the command should repeat.
- Run At: Specify the time at which the command should run. Enter the time in the 24-hour format: HH:MM, such as 13:30 (1:30 PM), or 03:30 (3:30 AM).
- Run on Trigger (webhook): Commands set to run on trigger execute when a webhook is received from an external source. Enter the name of the trigger. See Use Command Triggers.
- Note: The execution time for scheduled and repeating launch events corresponds with the target device’s time zone. In the Admin Portal, the event is labeled as Server Time.
- Run on Next Login: Run the command once on the next login of the JumpCloud-managed user.
- Note: Login commands apply only to logins from the device login screen, and not screen unlock and terminal logins. Additionally, next login commands will not run when rebinding the command to a device where the command has been previously bound.
- Run on Every Login: Run the command on every login of the JumpCloud-managed user.
- Note: Login commands apply only to logins from the device login screen, and not screen unlock and terminal logins.
- For Timeout After, enter a value in seconds. This determines how long the command can continue running before the agent will terminate it.
- For Time to Live (TTL) Settings, select a queue timeout to determine how long a command can sit in the queue before it’s automatically removed. This is useful when configuring commands to run on devices that are temporarily unavailable.
- Use Smart Defaults – Choose a predefined default timeout of 1 Hour, 1 Day, 3 Days, 7 Days, or 10 Days.
- Set Custom Duration – Enter a duration using Days and Hours, with a minimum of 1 hour and a maximum of 10 days.
A 3-day default is set for all new commands, unless a custom timeout is configured here. TTL isn’t applicable to scheduled or repeating commands.
- (Optional) Select Upload File to attach a file to the command. The file will then be available when the command executes on the endpoint. You can update the file any time, and the next time the command runs, it will have the latest update. There are no file type restrictions, but there’s a 1MB size limitation per file attachment and for command results logs.
If you want to use Commands to remotely install applications, see Install Applications Remotely.
- Select the Device Groups tab to set the specific device groups where this command will execute.
- Select the Devices tab to set the specific devices where this command will execute.
- (Optional) Select the Command Runners tab to select a user as a Command Runner with access to run the command. By default, Admins can run commands on all devices.
- Click Save.
- Run the command by clicking Run Now on the Commands page.
You can quickly delete a command in the Commands page by clicking Delete. You can remove multiple commands by selecting the checkbox next to the command and clicking Delete.
- Review the exit code that was reported by selecting the checkbox next to the command on the Commands page and selecting the Results tab. See Understand Command Results for a list of exit codes. If multiple commands are processed at runtime, only the last exit code is reported. Click view to see the results and log file.
- The times shown in the Command Results window are the current time on the device where the command ran and converted into UTC.
- Command results are stored for 30 days. After 30 days, results are removed and can’t be retrieved.
- Command results are only updated from the device following the execution of the command on that machine, so there isn’t a path for a command result to be generated for an offline device.
Understanding Scheduled Commands
When you create a scheduled or repeating command, it will run at the time specified in the device’s local time zone. If you have devices in multiple time zones, this can lead to undesired effects.
For example, assume that you reside in San Francisco, California, which is in Pacific Standard Time. Assume that the current time is 10:00 AM Pacific time and you schedule a command to run at 12:00 noon the same day. And finally, assume that you have devices in various time zones.
- Devices in Pacific Time execute the command at 12 noon PST, two hours after you completed scheduling the command.
- Devices in Mountain Time execute the command at 12 noon MST, one hour after you completed scheduling the command.
- Devices in Central Time execute the command at 12 noon CST, upon receiving the command. However, if the device does not receive the command in time, it may not run at all.
- Devices in Eastern Time won’t execute the command at all, as by the time the command was scheduled, 10:00 am PST, 12:00 noon EST will have already passed.
Command payloads expire after 10 minutes if they are not received by the device. If the device is online and receives the payload within the 10 minutes, the command is scheduled to run according to the configuration. If the scheduled time has already expired when the payload is received, the command will not run.
You should schedule commands with as much lead time as possible to accommodate your devices in other time zones. If your organization has a global presence, schedule commands at least 24 hours in advance.
Creating a Command from a Template
Creating a new command from a command template can save you time and reduce errors when running custom commands on your devices. You must be an Admin with Billing permissions to create a command from a template.
The JumpCloud Commands Gallery contains curated Mac, Windows, and Linux commands that are available for import using the JumpCloud PowerShell Module.
To create a command from a template:
- Log in to the JumpCloud Admin Portal.
- Go to DEVICE MANAGEMENT > Commands.
- Click ( + ) and choose Command from Template.
- In the ConfigureNew Command from Template window, perform these steps:
- Select the OS tab to view the existing command templates for that OS.
- Locate the template you want to use as a basis for your new command. You can quickly filter the list of templates by clicking filter by and choosing Default Templates or Custom Templates. A set of default templates come with JumpCloud, and custom templates help you automate tasks for a large number of devices.
- Click configure.
- In the New Command window, enter a unique name for the new command to differentiate it from other commands.
- For Type, select Linux, Windows or Mac.
- Make other necessary changes to the settings. For instructions on changing each field, see Creating a Command Manually above.
- Select the Device Groups tab to select the device groups where this command will execute.
- Select the Devices tab to select the devices where this command will execute.
- (Optional) Select the Command Runners tab to select a user as a Command Runner with access to run the command. By default, Admins can run commands on all devices.
- Click Save to create a new command.
- Run the command by locating in on the Commands page and clicking Run Now.
- Review the exit code that was reported by selecting the checkbox next to the command on the Commands page and selecting the Results tab. See Understand Command Results for a list of exit codes. If multiple commands are processed at runtime, only the last exit code is reported. Click view to see the results and log file.
Running an Ad Hoc Command on Devices
To run an ad hoc command on devices from the Devices panel:
- Click DEVICE MANAGEMENT > Devices then again on the Devices tab.
- An aggregate list of all your devices for that org will be displayed. You can search or filter for a specific device.
- Click the Actions dropdown menu next to the device you want to run the ad hoc command, and select Run Command.
- A list of existing commands associated with that device will be displayed. You can search for a command, or create a new one.
- To create a new one, click New Command, then give it a Name.
Note: Depending on the OS, some of the fields will be slightly different. For example, if it’s a Windows device, the option to run Windows Powershell will be available to select. For Mac and Linux, you’ll be required to select a user to run the command on the device under the Run as dropdown menu.
- Enter your Command, then under Timeout after, enter an amount of time in seconds.
- Under Time to Live (TTL) Settings, you can either Use Smart Defaults and select an amount of time from the dropdown menu, or Set Custom Duration and choose your own time to live.
- Then click Save And Run Command. This will save the command to the organization that the device is associated with and run the command on that device.
Note: You can re-use this command but it won’t be bound to any devices since it’s being run once, manually.
- If you want to see or cancel the command, from the org’s admin portal, click DEVICE MANAGEMENT > Commands > Queued for all commands being run on the device.
Creating a Command after Agent Install
A command created to run after agent install runs only once after the JumpCloud agent is installed on the device. These types of commands are useful for delivering applications and licensing information to new users during device provisioning, or for applying a naming policy to new devices.
To create a command after agent install:
- Log in to the JumpCloud Admin Portal.
- Go to DEVICE MANAGEMENT > Commands.
- Click ( + ) and choose Command After Agent Install.
- On the Details tab, enter a name for the new command. This is the name shown in the sortable list view of commands.
Note: If running more than one command for the same device type, commands will run in alphabetical order.
- For Type, select Linux, Windows, or Mac.
- Linux – Select the Run As user account that will run the command.
- Windows – Commands will be run as the LocalSystem account and optionally can be run as PowerShell.
- Mac – Select the Run As user account that will run the command.
- For Command, type or paste a script. The script can be in any language that your servers can execute.
- Configure additional command settings under Options and Files. For instructions on changing each field, see Creating a Command Manually above.
- Click Save. A “Command created successfully” message appears.
The JumpCloud Commands Gallery
The JumpCloud Commands Gallery contains curated Mac, Windows, and Linux commands that are available for import using the JumpCloud PowerShell module. This library of JumpCloud commands is hosted on GitHub and maintained by the JumpCloud solutions architecture and success teams.
Find quick links to navigate to sections of the JumpCloud Command Gallery below:
To import these commands, see Install the JumpCloud PowerShell Module first.
Once the Module has been installed, find at the bottom of each command a code block under the header Import This Command. Simply copy and paste the code from this section and run it in the PowerShell terminal to import the command into your JumpCloud tenant. Imported commands will be located within the Commands section of the JumpCloud Admin Portal. Alternatively, each command in the gallery can be created manually in the JumpCloud Admin Portal by copying and pasting the code block under the Command header into a new command within the JumpCloud Admin Portal.
To see the status of all commands run on Devices:
- Click DEVICE MANAGEMENT > Commands > Results to see all of the commands run, then click view to pull up the results details.