Installing osquery on Windows
For those needing more customization of their deployment, the steps taken by the installation are explained in more detail, below.
Installing with Chocolatey
Each osquery tag (stable release) is published to Chocolatey for our supported versions: https://chocolatey.org/packages/osquery/
By default Chocolatey will install the binaries, example packs, example configuration, and an OpenSSL certificate bundle to
C:\Program Files\osquery and nothing more. You can pass Chocolatey the
--params='/InstallService' flag or make use of osquery's
--install flag with
C:\Program Files\osquery\osqueryd\osqueryd.exe --install to install a Windows
SYSTEM-level service for the
Installing osquery via the MSI package
For generating an MSI installer package, we support two methods.
The first method is with minor modifications to the CMake build steps:
- First, install the Wix Toolset. With Chocolatey,
choco install wixtoolsetand then add
C:\Program Files (x86)\WiX Toolset v3.11\binto the system PATH. As of the time of this writing, the Chocolatey package installer doesn't add this to the PATH for you; you must add it yourself.
- When configuring the build, specify a version string for the osquery package using the CMake parameter
- When building, provide an additional CMake parameter,
An example of a CMake build that generates an MSI package:
cd \projects\osquery\build cmake -G "Visual Studio 16 2019" -A x64 -T v141 -DOSQUERY_VERSION="4.0.0" ..\src cmake --build . --config RelWithDebInfo --target package
The second method is to use the script
make_windows_package.ps1 included in the source tree. This is a PowerShell script that will generate an MSI package for installing osquery. Running
.\tools\deployment\make_windows_package.ps1 'msi' from the source root will generate a standalone MSI package along with the example packs, configuration, and OpenSSL cert bundle.
To get osquery running as a
SYSTEM-level service on Windows, one must ensure two things:
osqueryd.exeis running with safe permissions
- The Windows Service Control Manager has all of the correct information for running the daemon
osqueryd.exe daemon is considered safe if the binary and the directory in which the binary resides do not allow non-privileged write accesses and both are owned by either the Administrators group or the
The recommended way to set these ACLs is with PowerShell, and we've written a helper function to handle these permissions. To do so,
. source the file and call the function, as follows:
C:\Users\Thor\work\repos\osquery [master ≡] λ . .\tools\deployment\chocolatey\tools\osquery_utils.ps1 C:\Users\Thor\work\repos\osquery [master ≡] λ Set-SafePermissions C:\Program Files\osquery\osqueryd\ True
If you'd prefer to manually set the permissions, check the
C:\Program Files\osquery\osqueryd directory and ensure that no users or groups have write permissions with the exception of the Administrators group or the SYSTEM account. Read and execute permissions are expected and safe, so also ensure the Users group has both.
Now that osquery is properly laid out on the filesystem, we need to create a new Windows service to launch and manage the daemon. If you're using Chocolatey, you can pass the
--params='/InstallService' flag during installation to have Chocolatey set up the Windows service for you. In general, any method to install a Windows system service will suffice. You just need to ensure to specify the
--flagfile option in the service binary path, and give the full paths for both the daemon binary and flag file.
- To install the service using Powershell we bundle a helper function living in the repo at
.\tools\manage-osqueryd.ps1which can be invoked as follows:
C:\Program Files\osquery λ .\manage-osqueryd.ps1 -install -startupArgs "C:\Program Files\osquery\osquery.flags"
- If you'd rather use Powershell to manually create the service you can run:
C:\Users\Thor\work\repos\osquery [master ≡] λ New-Service -Name "osqueryd" -BinaryPathName "C:\Program Files\osquery\osqueryd\osqueryd.exe --flagfile=C:\Program Files\osquery\osquery.flags"
- Lastly, if you'd prefer to use the Windows service utility
sc.exeyou can use:
C:\Users\Thor\work\repos\osquery [master ≡] λ sc.exe create osqueryd type= own start= auto error= normal binpath= "C:\Program Files\osquery\osqueryd\osqueryd.exe --flagfile=\Program Files\osquery\osquery.flags" displayname= 'osqueryd'
Out of the box via the Chocolatey installation, one can run osquery in the interactive shell mode using
osqueryi. More commonly, however, the daemon is configured to be a system service. To set this up, you'll need to install the daemon via the service installation flags as detailed in the steps above, and then provide the daemon with a config file. The simplest way to get
osqueryd up and running is to rename the
C:\Program Files\osquery\osquery.example.conf file provided to
osquery.conf. Once the configuration file is in place, you can start the Windows service:
Start-Service osquerydif you're using Powershell
sc.exe start osquerydif you're using cmd.exe
We recommend configuring large fleets with Chef or SCCM.
Managing the daemon service
osquery provides a helper script for managing the osquery daemon service, which is installed to
If you'd like to create your own osquery Chocolatey package, you can run
.\tools\deployment\make_windows_package.ps1. This script will grab the built binaries, the
packs directory, the
osquery.example.conf, and attempt to find the OpenSSL
Enabling Windows Event Log support
In order to enable support for the Windows Event Log, you first have to install the manifest file. To install and uninstall it manually, you can use the built-in
wevtutil im C:\Program Files\osquery\osquery.man
wevtutil um C:\Program Files\osquery\osquery.man
The same operation can be performed using the osquery manager (
The manifest file path can also be overridden using the
To verify that everything has been configured correctly, open the Event Viewer and search for the osquery folder under
Applications and Services Logs/Facebook/osquery.
To instruct osquery to use the channel you just created, change the configuration file to use the windows_event_log logger plugin.