Command-line flags

The osquery shell and daemon use optional command-line (CLI) flags to control initialization, disable/enable features, and select plugins. These flags are powered by Google Flags and are somewhat complicated. Understanding how flags work in osquery will help with stability and greatly reduce issue debugging time.

Most flags apply to both tools, osqueryi and osqueryd. The shell contains a few more to help with printing and other helpful one-off modes of operation. Expect Linux, macOS, and Windows to include platform specific flags too. Most platform specific flags will control the OS API and library integrations used by osquery. Warning, this list is still not the 'complete set' of flags. Refer to the techniques below for obtaining ground truth and check other components of this Wiki.

Flags that do not control startup settings may be included as "options" within configuration. Essentially, any flag needed to help osquery determine and discover a configuration must be supplied via command-line arguments. Google Flags enhances this to allow flags to be set within environment variables or via a "master" flag file.

To see a full list of flags for your osquery version use --help or select from the osquery_flags table:

$ osqueryi
osquery> SELECT * FROM osquery_flags;

To see the flags that have been updated by your configuration, a flag file, or by the shell try:

osquery> SELECT * FROM osquery_flags WHERE default_value <> value;

Flagfile

A special flag, part of Google Flags, can be used to read additional flags from a line-delimited file. On macOS and Linux this --flagfile is the recommended way to add/remove the following CLI-only initialization flags.

--flagfile /etc/osquery/osquery.flags

Include line-delimited switches to be interpreted and used as CLI-flags:

--config_plugin=custom_plugin
--logger_plugin=custom_plugin
--distributed_plugin=custom_plugin
--watchdog_level=0

If no --flagfile is provided, osquery will try to find and use a "default" flagfile at /etc/osquery/osquery.flags.default. Both the shell and daemon will discover and use the defaults.

NOTICE: Flags in a flagfile should not be wrapped in quotes, shell-macro/variable expansion is not applied!

Configuration control flags

--config_plugin=filesystem

Config plugin name. The type of configuration retrieval, the default filesystem plugin reads a configuration JSON from disk.

Built-in options include: filesystem, tls

--config_path=/etc/osquery/osquery.conf

The filesystem config plugin's path to a JSON file. On macOS the default path is /var/osquery/osquery.conf. If you want to read from multiple configuration paths, create a directory: /etc/osquery/osquery.conf.d/. All files within that optional directory will be read and merged in lexical order.

--config_refresh=0

An optional configuration refresh interval in seconds. By default a configuration is fetched only at osquery load. If the configuration should be auto-updated, set a "refresh" time to a value in seconds greater than 0. If the configuration endpoint cannot be reached during runtime, the normal retry approach is applied (e.g., the tls config plugin will retry 3 times).

--config_accelerated_refresh=300

If a configuration refresh is used (config_refresh > 0) and the refresh attempt fails, the accelerated refresh will be used. This allows plugins like tls to fetch fresh data after having been offline for a while.

--config_check=false

Check the format of an osquery config and exit. Arbitrary config plugins may be used. osquery will return a non-0 exit if the parsing failed.

--config_dump=false

Request that the configuration JSON be printed to standard out before it is updated, then exit the process. In this case "updated" means applied to the active config. When osquery starts it performs an initial update from the config plugin. To quickly debug the content retrieved by custom config plugins use this in tandem with --config_check.

Daemon control flags

--force=false

Force osqueryd to kill previously-running daemons. The daemon will check for an existing "pidfile". If found, and if it contains a pid of a process named "osqueryd", the process will be killed.

--pidfile=/var/osquery/osqueryd.pidfile

Path to the daemon pidfile mutex. The file is used to prevent multiple osqueryd processes starting.

--disable_watchdog=false

Disable userland watchdog process. osqueryd uses a watchdog process to monitor the memory and CPU utilization of threads executing the query schedule. If any performance limit is violated, the "worker" process will be restarted.

--watchdog_level=0

Performance limit level (0=normal, 1=restrictive, -1=disabled). The watchdog process uses a "level" to configure performance limits.

The level limits are as follows: Memory: default 200M, restrictive 100M CPU: default 10% (for 12 seconds), restrictive 5% (for 6 seconds)

It is better to set the level to disabled (-1) rather than disabling the watchdog outright, as the worker/watcher concept is used for extensions auto-loading too.

The watchdog "profiles" can be overridden for Memory and CPU Utilization.

--watchdog_memory_limit=0

If this value is >0 then the watchdog level (--watchdog_level) for maximum memory is overridden. Use this if you would like to allow the osqueryd process to allocate more than 200M, but somewhere less than 10G. This memory limit is expressed as a value representing MB.

--watchdog_utilization_limit=0

If this value is >0 then the watchdog level (--watchdog_level) for maximum sustained CPU utilization is overridden. Use this if you would like to allow the osqueryd process to use more than 10% of CPU for --watchdog_latency_limit seconds of wall time.

This value sets a maximum number of allowed CPU cycles counted as the processes table's user_time and system_time. The default value is 10, meaning 10% of CPU utilization allowed.

The CPU utilization limit is calculated the following way:

cpu_limit_ms = number_of_cores * check_interval_ms * (watchdog_utilization_limit / 100.0)

Where: - number_of_cores is the number of all cpu cores (physical + virtual). - check_interval_ms is 3 seconds. It is how often the watchdog checks worker and extension processes for CPU utilization.

Example: On a 2020 MacBook with Quad-Core Intel Core i7, the number of physical cores is 4 but number_of_cores is 8, thus by default the CPU utilization limit is 2400ms meaning that every three seconds the processes are expected to use less than 2400ms of CPU time (10% of all the CPU time 8 * 3000ms).

NOTE: Before osquery 5.10.0, on systems with virtual cores, osquery is actually using the count of physical cores, which is normally half the amount, which results in setting the limit to half of the configured utilization (1200ms is actually 5% of the full 8 * 3000ms CPU time).

--watchdog_latency_limit=0

If this value is >0 then the watchdog level (--watchdog_level) for time allowed to spend at maximum sustained CPU utilization is overridden. Use this if you would like to allow the osqueryd process to use more than the cpu utilization limit for longer than the defaults.

This value is a duration in seconds that the watchdog allows osquery to spend at maximum sustained CPU utilization.

The default value is 12 seconds.

--watchdog_delay=60

A delay in seconds before the watchdog process starts enforcing memory and CPU utilization limits. The default value 60s allows the daemon to perform resource intense actions, such as forwarding logs, at startup.

--watchdog_forced_shutdown_delay=4

Amount of seconds to wait to issue a forced shutdown, after the watchdog has issued a graceful shutdown request to a worker or extension, due to resource limits being hit. Note that on Windows this doesn't have any effect currently, since the watchdog issues a TerminateProcess as a "graceful" shutdown, which immediately kills the process.

--enable_extensions_watchdog=false

By default the watchdog monitors extensions for improper shutdown, but NOT for performance and utilization issues. Enable this flag if you would like extensions to use the same CPU and memory limits as the osquery worker. This means that your extensions or third-party extensions may be asked to stop and restart during execution.

--enable_watchdog_debug=false

If set to true, every 3 seconds the watchdog will log the measured CPU utilization and memory footprint of all the monitored processes. (To generate the logs this flag requires --verbose to be set.)

--table_delay=0

Add a millisecond delay between multiple table calls (when a table is used in a JOIN). A 200 millisecond delay will trade about 20% additional time for a reduced 5% CPU utilization.

--hash_cache_max=500

The hash table implements a cache that is invalidated when file path inodes are changed. Eviction occurs in chunks if the max-size is reached. This max should remain relatively low since it will persist in the daemon's resident memory.

--hash_delay=20

Add a millisecond delay between multiple hash attempts (aka when scanning a directory). This adds about 50% additional wall-time for 150 files. This reduces the instantaneous resource need from hashing new files.

--disable_hash_cache=false

Set this to true if you would like to disable file hash caching and always regenerate the file hashes every request. The default osquery configuration may report hashes incorrectly if things are editing filesystems outside of the OS's control.

Windows-only daemon control flags

Windows builds include a --install and --uninstall that will create a Windows service using the osqueryd.exe binary and preserve an optional --flagfile if provided.

Backing storage control flags

--database_path=/var/osquery/osquery.db

If using a disk-based backing store, specify a path. osquery will keep state using a "backing store" using RocksDB by default. This state holds event information such that it may be queried later according to a schedule. It holds the results of the most recent query for each query within the schedule. This last-queried result allows query-differential logging.

--database_dump=false

Helpful for debugging database problems. This will print a line for each key in the backing store. Note: There could be MBs worth of data in the backing store.

Extensions control flags

--disable_extensions=false

Disable extension API. See the SDK development page for more information on osquery extensions, and the deployment page for how to use extensions.

--extensions_socket=/var/osquery/osquery.em

Path to the extensions UNIX domain socket. Extensions use a UNIX domain socket for communication. It is very uncommon to change the location of the file. The osquery shell may use extensions, but the socket location is relative to the user invoking the shell and does not support concurrent shells.

--extensions_autoload=/etc/osquery/extensions.load

Optional path to a list of auto-loaded and managed extensions. If using an extension to provide a proprietary config or logger plugin the extension process can be started by the daemon. Include line-delimited paths to extension executables. See the extensions deployment page for more details on extension auto-loading.

--extensions_timeout=3

Seconds to wait for auto-loaded extensions to register. osqueryd may depend on a config plugin from an extension. If the requested config plugin name is not registered within the timeout the daemon will exit with a failure.

--extensions_interval=3

Seconds delay between extension connectivity checks. Extensions are loaded as processes. They are expected to start a thrift service thread. The osqueryd process will continue to check this API. If an extension process is incorrectly stopped, osqueryd will detect the connectivity failure and unregister the extension.

--extensions_require=custom1,custom1

Optional comma-delimited set of extension names to require before osqueryi or osqueryd will start. The tool will fail if the extension has not started according to the interval and timeout.

--extensions_default_index=true

Enable INDEX (and thereby constraints) on all extension table columns. Provides backwards compatibility for extensions (or SDKs) that don't correctly define indexes in column options. See issue 6006 for more details.

Remote settings flags (optional)

When using non-default remote plugins such as the tls config, logger and distributed plugins, there are process-wide settings applied to every plugin.

--tls_hostname=

When using tls-based config or logger plugins, a single TLS host URI is used. Using separate hosts for configuration and logging is not supported among the tls-based plugin suite. Provide a host name and optional port, e.g.: facebook.com or facebook.com:443.

--tls_session_reuse=true

Reuse TLS session sockets.

--tls_session_timeout=3600

Once a socket is created, the lifetime is governed by this flag. If this value is set to 0, then transport never times out unless the remote end closes the connection or an error occurs.

--tls_client_cert=

See the tls/remote plugin documentation. Optionally provide a path to a PEM-formatted client TLS certificate.

--tls_client_key=

See the tls/remote plugin documentation. Optionally provide a path to a decrypted/password-less PEM-formatted client TLS private key.

--tls_server_certs=

See the tls/remote plugin documentation. Optionally provide a path to a PEM-formatted server or authority certificate bundle. This path will be used as either an explicit set of accepted certificates or an OpenSSL-verify path directory of well-formed filename certificates.

--disable_enrollment=false

See the tls/remote plugin documentation. Remote plugins use an enrollment process to enable possible server-side implemented authentication and identification/authorization. Config and logger plugins implicitly require enrollment features. It is not recommended to disable enrollment and this option may be removed in the future.

--enroll_secret_path=

See the tls/remote plugin documentation. A very simple authentication/enrollment involves posting a deployment or staged shared secret. This secret should be protected on the host, but potentially shared among an enterprise or fleet. Provide a path for the osquery process to read and use during enrollment phases.

--config_tls_endpoint=

The tls endpoint path, e.g.: /api/v1/config when using the tls config plugin. See the other tls_ related CLI flags.

--config_tls_max_attempts=3

The total number of attempts that will be made to the remote config server if a request fails. If an attempt fails, it will be retried with exponential backoff, up to the max number of attempts set.

--logger_tls_endpoint=

The tls endpoint path, e.g.: /api/v1/logger when using the tls logger plugin. See the other tls_ related CLI flags.

--enroll_tls_endpoint=

See the tls/remote plugin documentation. An enrollment process will be used to allow server-side implemented authentication and identification/authorization. You must provide an endpoint relative to the --tls_hostname URI.

--tls_enroll_max_attempts=12

The total number of attempts that will be made to the remote enroll server if a request fails. If an attempt fails, it will be retried up to the max number of attempts set, with exponential backoff limited by the flag --tls_enroll_max_interval. If the flag is set to 0, the amount of attempts will be infinite.

--tls_enroll_max_interval=600

Maximum wait time in seconds between enroll retry attempts. This works in conjunction with --tls_enroll_max_attempts, and affects both the limited and the infinite attempts case.

--logger_tls_period=3

See the tls/remote plugin documentation. This is a number of seconds before checking for buffered logs. Results are sent to the TLS endpoint in intervals, not on demand (unless the period=0).

--logger_tls_compress=false

Optionally enable GZIP compression for request bodies when sending. This is optional and disabled by default, as the deployment must explicitly know that the logging endpoint supports GZIP for content encoding.

--logger_tls_max_linesize=1048576

It is common for TLS/HTTPS servers to enforce a maximum request body size. The default behavior in osquery is to enforce each log line be under 1MB (1048576 bytes). This means each result line from a query's results cannot exceed 1M, this is very unlikely. Each log attempt will try to forward up to 1024 lines. If your service is limited request bodies, configure the client to limit the log line size.

Use this only in emergency situations as size violations are dropped. It is extremely uncommon for this to occur, as the --value_max for each column would need to be drastically larger, or the offending table would have to implement several hundred columns.

--logger_tls_max_lines=1024

This configures the max number of log lines to send every period (meaning every logger_tls_period).

--logger_tls_backoff_max=3600

Maximum seconds to wait before flushing logs over TLS/HTTPS. The exponential backoff kicks in when regular flush of buffered logs fails. Should be a multiple of logger_tls_period. 0 disables backoff. The max backoff time can be updated dynamically via config_tls_endpoint.

--distributed_tls_read_endpoint=

The URI path which will be used, in conjunction with --tls_hostname, to create the remote URI for retrieving distributed queries when using the tls distributed plugin.

--distributed_tls_write_endpoint=

The URI path which will be used, in conjunction with --tls_hostname, to create the remote URI for submitting the results of distributed queries when using the tls distributed plugin.

--distributed_tls_max_attempts=3

The total number of attempts that will be made to the remote distributed query server if a request fails when using the tls distributed plugin.

Daemon runtime control flags

--schedule_splay_percent=10

Percent to splay config times. The query schedule often includes several queries with the same interval. It is often not the intention of the schedule author to run these queries together at that interval. But rather, each query should run at about the interval. A default schedule splay of 10% is applied to each query when the configuration is loaded.

--schedule_max_drift=60

Max time drift in seconds. The scheduler tries to compensate the splay drift until the delta exceeds this value. If the max drift is exceeded the splay will be reset to zero and the compensation process will start from the beginning. This is needed to avoid the problem of endless compensation (which is CPU greedy) after a long SIGSTOP/SIGCONT pause or something similar. Set it to zero to disable drift compensation.

--pack_refresh_interval=3600

Query Packs may optionally include one or more discovery queries, which allow you to use osquery queries to manage which packs should be loaded at runtime. osquery will natively re-run the discovery queries from time to time, to make sure that all of the correct packs are executing. This flag allows you to specify that interval.

--pack_delimiter=_

Control the delimiter between pack name and pack query names. When queries are added to the daemon's schedule they inherit the name of the pack. A query named info within the general_info pack will become pack_general_info_info. Changing the delimiter to "/" turned the scheduled name into: pack/general_info/info.

--disable_caching=false

"Caching" refers to short cutting the table implementation and returning the same results from the previous query against the table. This is not related to differential results from scheduled queries, but does affect the performance of the schedule. Results are cached when different scheduled queries in a schedule use the same table, without providing query constraints. Caching should NOT affect data freshness since the cache life is determined as the minimum interval of all queries against a table.

--schedule_default_interval=3600

Optionally set the default interval value. This is used if you schedule a query which does not define an interval.

--schedule_timeout=0

Limit the schedule. Use 0 for no limit. Optionally limit the osqueryd's life by adding a schedule limit in seconds. This should only be used for testing.

--disable_tables=table_name1,table_name2

Comma-delimited list of table names to be disabled. This allows osquery to be launched without certain tables.

--read_max=52428800 (50 MB)

Maximum file read size. The daemon or shell will first 'stat' each file before reading. If the reported size is greater than read_max a "file too large" error will be returned.

Linux-only runtime control flags

--malloc_trim_threshold=200

Memory threshold in MB used to decide when a malloc_trim will be called to reduce the retained memory. When the flag is not provided, the value will be chosen automatically between 80% of the watchdog_memory_limit if the watchdog is not disabled and 200MB in the case it is. Providing the flag with a value always overrides the automatic behavior and setting it to 0 completely disables calling malloc_trim. This is an attempt to reduce the amount of memory that the malloc allocator has in its caches in the worker process, which sometimes leads to hitting the watchdog memory limit more often. The downside is that in some cases there can be a performance hit in a query execution, since the cache was there to speed up future allocations. Note: When the watchdog starts, it takes a snapshot of the amount of memory that the worker uses in that moment; from that value then it adds the allocated memory limit set in watchdog_memory_limit and finds at how much memory used by the worker it should trigger. This means that if the watchdog_memory_limit is set to 200MB, the watchdog triggers at 200MB + something (around 15 to 30MB) used, not at 200MB. The malloc_trim system though doesn't have access to that information, so the best thing it can do is to use watchdog_memory_limit to calculate its own threshold. This should be good enough, but the user should be aware that how soon malloc_trim acts in respect to how soon the watchdog would've acted is actually slightly variable.

Windows-only runtime control flags

--users_service_delay=250

Defines the amount of milliseconds to wait during a scan of users information, between a batch of 100 users and the other. This is meant to throttle the CPU usage of osquery and especially the LSASS process on a Windows Server DC. The first users batch is always gathered immediately at the start of the scan.

--users_service_interval=1800

Defines the amount of seconds to wait between full scans of users information. The background service first obtains a list of all the users that are present on a machine, then start obtaining their details, using users_service_delay to slow down the process, then when the whole list has been processed, it will sleep users_service_interval seconds.

--groups_service_delay=150

Works the same as users_service_delay, but for the groups service. The default value is lower because collecting groups information is less performance intensive.

--groups_service_interval=1800

Works the same as users_service_interval, but for the groups service.

Events control flags

--disable_events=false

Disable or enable osquery Operating System eventing publish-subscribe APIs. Setting this to true (which is the default value) disables tables that report evented data (tables whose names end with _events) and querying them will generate a warning.

--events_expiry=3600

Expiration age for evented data (in seconds), applied once the data is queried. Until an evented table is queried, its collected events are cached in backing-store. Events are only expired (i.e., removed from the table) when the evented table is queried. For example, if --events_expiry=1, then events older than 1 second will only appear in the next SELECT from the subscriber. If no SELECT occurs, those events will be saved in the backing store indefinitely or until the events_max limit is reached (see below). If, on the other hand, the table contains recent events that have not yet reached expiration age, the same table can be queried repeatedly in quick succession and the same data will continue to be present unless it had reached the expiration age when it was last queried, at which point it will be removed. 3600 seconds is the default, but if querying on an interval shorter than 3600, you may wish to lower this value to avoid retrieving duplicate events.

--events_optimize=true

Since event rows are only "added" it does not make sense to emit "removed" results. An optimization can occur within the osquery daemon's query schedule. Every time the SELECT query runs on a subscriber, the current time is saved. Subsequent SELECTs will use the previously saved time as the lower bound. This optimization is removed if any constraints on the "time" column are included.

--events_max=50000

Maximum number of events to buffer in the backing store while waiting for a query to "drain" them (if and only if the events are old enough to be expired out, see above). For example, the default value indicates that a maximum of the 50000 most recent events will be stored. The right value for your osquery deployment, if you want to avoid missed/dropped events, should be considered based on the combination of your host's event occurrence frequency and the interval of your scheduled queries of those tables.

--events_enforce_denylist=false

This controls whether watchdog denylisting is enforced on queries using "*_events" (event-based) tables. As these these queries operate on meta-generated table logic, performance issues are unavoidable. It does not make sense to denylist. Enforcing this may lead to adverse and opposite effects because events will buffer longer and impact RocksDB storage.

This only considers queries that are entirely event-based. For example SELECT * FROM process_events is considered, but SELECT * FROM process_events join time is not.

It is not recommended to set this to true.

Windows-only events control flags

--enable_ntfs_event_publisher Enables the NTFS event publisher

--enable_powershell_events_subscriber Enables Powershell events

--enable_windows_events_publisher Enables the Windows events publisher

--enable_windows_events_subscriber Enables Windows Event Log events

On Windows, in addition to the --disable_events=false flag mentioned above, each category of evented data must also be enabled individually, by enabling the corresponding osquery publisher and osquery subscriber. By default, all are disabled, and the corresponding evented tables will be empty. Note that an event publisher within osquery subscribes to events from the OS and then publishes them to an osquery event subscriber. For the current complete list of event sources usable by osquery, see osqueryi.exe --help | findstr -i Event.

--windows_event_channels=System,Application,Setup,Security

List of Windows Event Log channels for osquery to subscribe to. By default, osquery's Windows Event Log publisher will deliver some of the more common major event log channels. However, you can select additional channels using the Log Name field value in the Windows event viewer. Note the lack of quotes around the channel names. For example, to subscribe to Windows PowerShell script block logging, one would first enable the feature in Windows itself, and then subscribe to the channel with --windows_event_channels=Microsoft-Windows-PowerShell/Operational

Linux-only events control flags

--hardware_disabled_types=partition

This is a comma-separated list of UDEV types to drop. On machines with flash-backed storage it is likely you'll encounter lots of noise from disk and partition types.

macOS-only events control flags

--disable_endpointsecurity=true

Setting to false (in combination with --disable_events=false) turns on EndpointSecurity-based event collection within osquery (supported in macOS 10.15 and newer), and enables the use of the es_process_events table. This feature requires running osquery as root. It also requires that the osquery executable be code-signed and notarized to have the Endpoint Security client entitlement; official release builds of osquery will be appropriately code-signed. Lastly, it requires that the host give Full Disk Access permission to the osqueryd executable; for more information see the process auditing section of osquery's deployment documentation as well as installing osquery on macOS.

--disable_endpointsecurity_fim=true

Setting to false (in addition to --disable_events=false and --disable_endpointsecurity=false) will turn on EndpointSecurity based file event collection in osquery, running on macOS 10.15 and newer. This enables the use of es_process_file_events table.

--es_fim_mute_path_literal

This is a comma delimited list of path literals, which when set, is passed to EndpointSecurity based es_process_file_events table. This will result in events being muted for the paths set in here.

--es_fim_mute_path_prefix

This is a comma delimited list of path prefixes, which when set is passed to EndpointSecurity based es_process_file_events table. This will result in events being muted which match the path prefixes.

Logging/results flags

--logger_plugin=filesystem

Logger plugin name. The default logger is filesystem. This writes the various log types as JSON to specific file paths.

Multiple logger plugins may be used simultaneously, effectively copying logs to each interface. Separate plugin names with a comma when specifying the configuration (--logger_plugin=filesystem,syslog).

Built-in options include: filesystem, tls, syslog, and several Amazon/AWS options.

--disable_logging=false

Disable ERROR/WARNING/INFO (a.k.a. status logs) and query result logging.

--logger_event_type=true

Log scheduled results as events.

--logger_snapshot_event_type=false

Log scheduled snapshot results as events, similar to differential results. If this is set to true then each row from a snapshot query will be logged individually.

--logger_min_status=0

The minimum level for status log recording. Use the following values: INFO = 0, WARNING = 1, ERROR = 2. To disable all status messages use 3 or higher. When using --verbose, this value is ignored.

--logger_min_stderr=0

The minimum level for status logs written to stderr. Use the following values: INFO = 0, WARNING = 1, ERROR = 2. To disable all status messages use 3 or higher. It does not limit or control the types sent to the logger plugin. When using --verbose this value is ignored.

--logger_stderr=true

The default behavior is to also write status logs to stderr. Set this flag to false to disable writing (copying) status logs to stderr. In this case --verbose is respected.

--logger_path=/var/log/osquery/

Directory path for ERROR/WARN/INFO and query result logging by the filesystem plugin.

--logger_mode=0640

File mode for output log files by the filesystem plugin, provided as an octal string. Note that this affects both the query result log and the status logs and only works on POSIX platforms. (Versions previous to osquery 5.0.0 were incorrectly interpreting logger_mode as a number in decimal format, not octal.) Warning: If run as root, log files may contain sensitive information!

--logger_rotate=false

When enabled, the filesystem plugin will rotate logs based on size. An example includes /var/log/osquery/osqueryd.results.log being rotated to /var/log/osquery/osqueryd.results.log.1 when the trigger size is reached. Files after the first rotation will be Zstandard-compressed and will use the .zst file extension. A max number of log files will be maintained and logs overflowing this count will be deleted after rotation.

--logger_rotate_size=26214400 (25MB)

A size, specified in bytes, to trigger rotation when enabled with --logger_rotate. A result or snapshot log will be rotated when it grows past this size. The size is checked before each new write to the logfile.

--logger_rotate_max_files=25

The max number of result and snapshot rotation files. The count applies to each individually, meaning by default osquery will maintain 25 results files and 25 snapshot files. If a rotation happens after hitting this max, the oldest file will be removed.

--logger_syslog_facility

Set the syslog facility (number) 0-23 for the results log by the syslog plugin. When using the syslog logger plugin, the default facility is 19 at the LOG_INFO level, which does not log to /var/log/system.

--logger_syslog_prepend_cee

Prepend a @cee: cookie to JSON-formatted messages sent to the syslog logger plugin. Several syslog parsers use this cookie to indicate that the message payload is parseable JSON. The default value is false.

--logger_kafka_brokers

A comma-delimited list of Kafka brokers to connect to. Format can be protocol://host:port, host:port or just host with the port number falling back to the default value of 9092. protocol can be plaintext (default) or ssl. When protocol is ssl, --tls_server_certs value is used as certificate trust store. Optionally --tls_client_cert and --tls_client_key can be provided for TLS client authentication with Kafka brokers.

--logger_kafka_topic

The Kafka topic to publish logs to. When using multiple topics this configuration becomes the base topic that unconfigured queries fall back to. Please see the Kafka section of the logging wiki for more details.

--logger_kafka_acks

The number of acknowledgments the Kafka leader has to receive before a publish is considered successful. Valid options are (0, 1, "all").

--logger_kafka_compression

Compression codec to use for compressing message sets. Valid options are ("none", "gzip"). Default is "none".

--buffered_log_max=1000000

There are multiple logger plugins that use a "buffered logging" implementation. The TLS and AWS loggers use this approach. This flag sets the maximum number of logs to buffer before dropping new logs. If the buffered logs have not been shuttled to the logger destination they will be purged in order of their timestamp. The oldest logs are purged first.

Setting this to value to 0 means unlimited logs will be buffered.

--host_identifier=hostname

Field used to identify the host running osquery: hostname, uuid, ephemeral, instance, specified.

DHCP may assign variable hostnames, if this is the case, you may need a consistent logging label. Four options are available to you:

• uuid uses the platform (DMTF) host UUID, fetched at process start.
• instance uses an instance-unique UUID generated at process start, persisted in the backing store.
• ephemeral uses an instance-unique UUID generated at process start, not persisted.
• specified uses an ID provided by the --specified_identifier flag.

--specified_identifier=this.is.the.identifier

If --host_identifier=specified is set, use this value as the host identifier.

--verbose=false

Enable verbose informational messages.

--thrift_verbose=false

Enable thrift global output.

--value_max=512

Maximum returned row value size.

--schedule_lognames=false

Log executing scheduled query names at the INFO level, and not the VERBOSE level

--distributed_loginfo=false

Log executing distributed queries at the INFO level, and not the VERBOSE level

--decorations_top_level

Add decorators as top level JSON object members instead of being nested in a decorations member; this works for both result and status logs. For more details look at Decorator queries paragraph.
NOTE: Since osquery 5.10 the standard decorations like unixTime, severity and line are represented as true numbers in JSON, not as their string representations.

Distributed query service flags

--distributed_plugin=tls

Distributed plugin name. The default distributed plugin is not set. You must set --disable_distributed=false --distributed_plugin=tls (or whatever plugin you'd rather use instead of TLS) to enable the distributed feature.

--disable_distributed=true

Disable distributed queries functionality. By default, this is set to true (the distributed feature is disabled). Set this to false to enable distributed queries.

--distributed_interval=60

In seconds, the amount of time that osqueryd will wait between periodically checking in with a distributed query server to see if there are any queries to execute.

Syslog consumption flags

There is a syslog virtual table that uses Events and a rsyslog configuration to capture results from syslog. Please see the Syslog Consumption deployment page for more information.

--enable_syslog=false

Turn on the syslog ingestion event publisher. This is an 'explicit'-enable because it requires external configuration of rsyslog.

--syslog_pipe_path=/var/osquery/syslog_pipe

Path to the named pipe used for forwarding rsyslog events.

--syslog_rate_limit=100

Maximum number of logs to ingest per run (~200ms between runs). Use this as a fail-safe to prevent osquery from becoming overloaded when syslog is spammed.

Augeas flags

--augeas_lenses=/opt/osquery/share/osquery/lenses

Augeas lenses are bundled with osquery distributions. On Linux they are installed in /opt/osquery/share/osquery/lenses. On macOS, lenses are installed in the /private/var/osquery/lenses directory. Specify the path to the directory containing custom or different version lenses files.

Docker flags

--docker_socket=/var/run/docker.sock

Docker information for containers, networks, volumes, images etc is available in different tables. osquery uses docker's UNIX domain socket to invoke docker API calls. Provide the path to Docker's domain socket file. User running osqueryd / osqueryi should have permission to read the socket file.

Shell-only flags

Most of the shell flags are self-explanatory and are adapted from the SQLite shell. Refer to the shell's .help command for details and explanations.

There are several flags that control the shell's output format: --json, --list, --line, --csv. For all of the output types there is --nullvalue and --separator that can be used appropriately.

--planner=false

When prototyping new queries, the planner enables verbose decisions made by the SQLite virtual table API. This is customized by osquery code so it is very helpful to learn what predicate constraints are selected and what full-table scans are required for JOIN and nested queries.

--header=true

Set this value to false to disable column name (header) output. If using the shell in an automation or script the header line in line or csv mode may not be needed.

Numeric monitoring flags

--enable_numeric_monitoring=false

Enable numeric monitoring system. By default it is disabled.

--numeric_monitoring_plugins=filesystem

Comma-separated numeric monitoring plugins. By default there is only one: filesystem.

--numeric_monitoring_pre_aggregation_time=60

Time period in seconds for numeric monitoring pre-aggregation buffer. During this period of time, monitoring points will be pre-aggregated and accumulated in a buffer. At the end of this period, the aggregated points will be flushed to --numeric_monitoring_plugins. 0 means to work without a buffer at all. For most monitoring data, some aggregation will be applied on the user side. In these cases, particular points don't mean much. To reduce disk usage and network traffic, some pre-aggregation is applied on the osquery side.

--numeric_monitoring_filesystem_path=OSQUERY_LOG_HOME/numeric_monitoring.log

File to dump numeric monitoring records one per line. The format of the line is <PATH><TAB><VALUE><TAB><TIMESTAMP>. File will be opened in append mode.

Enable and Disable flags

--disable_tables=table1,table2

Comma separated list of tables to disable. By default no tables are disabled.

--enable_tables=table1,table2

Comma separated list of tables to enable. By default every table is enabled. If a specific table is set in both --enable_tables and --disable_tables, disabling take precedence. If --enable_tables is defined and --disable_tables is not set, every table but the one defined in --enable_tables become disabled.

AWS

--aws_imdsv2_request_attempts=3

How many attempts to do at requesting an IMDSv2 token. Such a token is retrieved from an AWS metadata service that might not always be accessible, and it's used by plugins like the loggers AWS Kinesis, AWS Firehose or the EC2 tables.

--aws_imdsv2_request_interval=3

Base seconds to wait between attempts at requesting an IMDSv2 token. Scales quadratically with the number of attempts.

--aws_disable_imdsv1_fallback=false

Whether to disable support for IMDSv1 and fail if an IMDSv2 token could not be retrieved

--aws_enforce_fips

Enforces that only FIPS endpoints can be used for the logger plugins (Kinesis, Firehose), the STS authentication and the EC2 tables.
Using a non compliant region for the logger plugins will cause osquery to fail to start; for other non compliant cases the specific service will fail to work.
In all non compliant cases, an error or warning message will be printed. In verbose mode an additional message will show if a certain service has FIPS enforced.

--aws_region

Configure the default region to use for the AWS services and tables. If not specified and a more specific region flag is not provided, a fallback mechanism will be used, which will try to read the local profile configuration and take the region from there.
If that fails too, the default region of us-east-1 will be chosen.

--aws_sts_region

Configure the region to use when acquiring STS credentials. If not specified, the --aws_region flag value will be used if set, otherwise its fallback mechanism will be used.

--aws_firehose_region

Configure the region to use for the AWS Firehose logger plugin. If not specified, the --aws_region flag value will be used if set, otherwise its fallback mechanism will be used.

--aws_kinesis_region

Configure the region to use for the AWS Kinesis logger plugin. If not specified, the --aws_region flag value will be used if set, otherwise its fallback mechanism will be used.

macOS keychain flags

By default, Osquery limits frequent access to keychain files on macOS. This limit applies to certificates, keychain_acls, and keychain_items tables.

--keychain_access_cache=true

Whether to use a cache for keychain access (default true). The cache resides in-memory, and independent entries are used for each table and keychain file. If the keychain file has NOT been modified, osquery will return the cached result. The cache does not expire. It is cleared when osquery is restarted.

--keychain_access_interval=5

Minimum minutes required between keychain accesses (default is 5). Keychain cache must be enabled. The access interval is the minimum time that must elapse before osquery will open and read a keychain file. Starting from the first access and until time + --keychain_access_interval, osquery will return cached results for a given keychain file. The interval is applied independently for each table. Therefore, multiple tables can read the same keychain file, but they can only do so once within the interval. Since keychain files are generally not updated frequently, we expect that most keychain accesses will not be impacted by this interval. To disable the keychain access interval: --keychain_access_interval=0