Add docs for script execution (#13807)

- Add doc page for run a script via CLI story (#9583).
2023-09-12 18:31:04 -04:00
parent 6026130a8e
commit 8600c8fe14
5 changed files with 81 additions and 5 deletions
@@ -1,7 +1,7 @@
 <!-- DO NOT EDIT. This document is automatically generated. -->
 # Audit logs

-Fleet logs the following information for administrative actions (in JSON):
+Fleet logs the following information for administrative activities (in JSON):

 - `created_at`: Timestamp of the event.
 - `id`: Unique ID of the generated event in Fleet.
@@ -28,8 +28,12 @@ Example:
 	}
 }
 ```
+
+You can automatically send these logs to your log destination. Learn how to configure this [here](https://fleetdm.com/docs/configuration/fleet-server-configuration#external-activity-audit-logging).
+
+To view activities in the UI, click the Fleet icon in the top navigation bar and locate the **Activity** section.
 	
-## List of activities and their specific details
+## Activity types

 ### Type `created_pack`

@@ -60,7 +60,7 @@ Fleet UI:

 ### Step 3: run the command

-1. Run the `fleetctl mdm run-command --payload=restart-device.xml --host=hostname `
+1. Run the `fleetctl mdm run-command --payload=restart-device.xml --host=hostname ` command.
 > Replace the --payload and --host flags with your `.xml` file and hostname respectively.

 2. Look at the on-screen information. In the output you'll see the command required to see results. Be sure to copy this command. If you don't, it will be difficult to view command results later.
@@ -0,0 +1,67 @@
+# Scripts
+
+_Available in Fleet Premium_
+
+In Fleet you can execute a custom script to remediate an issue on your macOS, Windows, and Linux hosts.
+
+Shell scripts are supported on macOS and Linux. All scripts will run in the host's (root) default shell (`/bin/sh`). Other interpreters are not supported yet.
+
+PowerShell scripts are supported on Windows. Other types of scripts are not supported yet.
+
+Script execution is disabled by default. Continue reading to learn how to enable scripts.
+
+## Execute a script
+
+You can execute a script using the `fleetctl` command-line interface.
+
+To execute a script, we will do the following steps:
+1. Enable script execution
+2. Write a script
+3. Run the script
+
+### Step 1: Enable script execution
+
+If you use Fleet's macOS MDM features, scripts are automatically enabled for macOS hosts that have MDM turned on. You're set!
+
+If you don't use MDM features, to enable scripts, we'll deploy a fleetd agent with scripts enabled:
+
+1. Generate a new fleetd agent for macOS, Windows, or Linux using the `fleetctl package` command with the `--enable-scripts` flag. 
+
+2. Deploy fleetd to your hosts. If your hosts already have fleetd installed, you can deploy the new fleetd on-top of the old installation.
+
+Learn more about generating a fleetd agent and deploying it [here](./enroll-hosts.md#enroll-hosts-with-fleetd).
+
+### Step 2: Write a script
+
+As an example, we'll write a shell script for a macOS host that downloads a Fleet wallpaper and set the host's wallpaper to it.
+
+To run the script, we'll need to create a `set-wallpaper-to-fleet.sh` file locally and copy and paste this script into this `.sh` file:
+
+```sh
+wallpaper="/tmp/wallpaper.png" 
+
+curl --fail https://fleetdm.com/images/wallpaper-cloud-city-1920x1080.png -o $wallpaper
+
+osascript -e 'tell application "Finder" to set desktop picture to POSIX file "'"$wallpaper"'"' 
+```
+
+### Step 3: Run the script
+
+1. Run the `fleetctl run-script --script_path=set-wallpaper-to-fleet.sh --host=hostname` command.
+
+> Replace --host flag with your target host's hostname respectively.
+
+2. Look at the on-screen information. In the output you'll see the script's exit code and output.
+
+Each time a Fleet user runs a script an entry is created in [Fleet's activity feed](./Audit-logs.md#type-code-ran-script-code).
+
+## Security considerations
+
+Script execution can only be enabled by someone with root access to the host.
+
+Turning MDM on for a macOS host or pushing a new fleetd agent qualify as root access.
+
+<meta name="pageOrderInSection" value="1506">
+<meta name="title" value="Scripts">
+<meta name="description" value="Learn how to execute a custom script on macOS, Windows, and Linux hosts in Fleet.">
+<meta name="navSection" value="Device management">
@@ -17,7 +17,7 @@ func main() {
 	b.WriteString(`<!-- DO NOT EDIT. This document is automatically generated. -->
 # Audit logs

-Fleet logs the following information for administrative actions (in JSON):
+Fleet logs the following information for administrative activities (in JSON):

 - ` + "`" + `created_at` + "`" + `: Timestamp of the event.
 - ` + "`" + `id` + "`" + `: Unique ID of the generated event in Fleet.
@@ -44,8 +44,12 @@ Example:
 	}
 }
 ` + "```" + `
+
+You can automatically send these logs to your log destination. Learn how to configure this [here](https://fleetdm.com/docs/configuration/fleet-server-configuration#external-activity-audit-logging).
+
+To view activities in the UI, click the Fleet icon in the top navigation bar and locate the **Activity** section.
 	
-## List of activities and their specific details
+## Activity types

 `)

@@ -64,6 +68,7 @@ Example:
 		}
 	}
 	b.WriteString(`
+<meta name="title" value="Audit logs">
 <meta name="pageOrderInSection" value="1400">
 <meta name="description" value="Learn how Fleet logs administrative actions in JSON format.">
 <meta name="navSection" value="Dig deeper">