The osquery shell and daemon use optional command line (CLI) flags to control initialization, disable/enable features, and select plugins.
Most of these flag-based parameters apply to both tools. Flags that do not
control startup settings may be included as "options" to the daemon within its configuration. To see a full list of flags for your osquery version use
--help or select from the flags table:
osquery> select * from osquery_flags;
To see the flags that have been updated by your configuration, flagfile, or by the shell consider:
osquery> select * from osquery_flags where default_value <> value;
CLI-only (initialization) flags
A special flag, part of Gflags, can be used to read additional flags from a line-delimited file. On OS X and Linux this flagfile is the recommended way to add/remove the following CLI-only initialization 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 --watchlog_level=2
Configuration control flags
Config plugin name. The type of configuration retrieval, the default filesystem plugin reads a configuration JSON from disk.
Built-in options include: filesystem, tls
The filesystem config plugin's path to a JSON file. On OS X 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.
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.
Request that the configuration JSON be printed to standard out before it is updated. 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
osquery daemon control flags
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.
Path to the daemon pidfile mutex. The file is used to prevent multiple osqueryd processes starting.
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.
Performance limit level (0=loose, 1=normal, 2=restrictive, 3=debug). The default watchdog process uses a "level" to configure performance limits. The higher the level the more strict the limits become. The "debug" level disables the performance limits completely.
Attempt to convert all UNIX calendar times to UTC. In version 1.8.0 this will be
true by default.
Backing storage control flags
Keep osquery backing-store in memory. This has a number of performance implications and is not recommended. For the default backing-store, RocksDB, this option is not supported.
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.
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
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.
Optional path to a list of autoloaded 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 autoloading.
Seconds to wait for autoloaded 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.
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.
Optional path to a list of autoloaded library module-based extensions. Modules are similar to extensions but are loaded as shared libraries. They are less flexible and should be built using the same GCC runtime and developer dependency library versions as osqueryd. See the extensions deployment page for more details on extension module autoloading.
Remote settings (optional for config/logger/distributed) flags
When using non-default remote plugins such as the tls config, logger and distributed plugins, there are process-wide settings applied to every plugin.
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.:
See the tls/remote plugin documentation. Optionally provide a path to a PEM-formatted client TLS certificate.
See the tls/remote plugin documentation. Optionally provide a path to a decrypted/password-less PEM-formatted client TLS private key.
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.
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.
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.
The tls endpoint path, e.g.: /api/v1/config when using the tls config plugin. See the other tls_ related CLI flags.
The configuration tls endpoint refresh interval. 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. This option enforces a minimum of 10 seconds. If the configuration endpoint cannot be reached during run, during an attempted refresh, the normal retry approach is applied.
The total number of attempts that will be made to the remote config server if a request fails.
The tls endpoint path, e.g.: /api/v1/logger when using the tls logger plugin. See the other tls_ related CLI flags.
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.
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).
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.
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 1M 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.
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.
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.
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.
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.
Maximum non-super user read size.
--read_max but applied to user-controlled (owned) files.
Read user-controlled (owned) filesystem links. This allows specific control over symbolic links owned by users.
osquery daemon runtime control flags
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.
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.
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".
"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.
Optionally set the default interval value. This is used if you schedule a query which does not define an interval.
Number of work dispatch threads.
Limit the schedule, 0 for no limit. Optionally limit the osqueryd's life by adding a schedule limit in seconds. This should only be used for testing.
Comma-delimited list of table names to be disabled. This allows osquery to be launched without certain tables.
osquery events control flags
Disable osquery Operating System eventing publish subscribe APIs. This will implicitly disable several tables that report based on logged events.
Timeout to expire eventing publish subscribe results from the backing-store. This expiration is only applied when results are queried. For example, if
--events_expiry=1 then events will only practically exist for a single select from the subscriber. If no select occurs then events will be saved in the backing store indefinitely.
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.
Maximum number of events to buffer in the backing store while waiting for a query to 'drain' or trigger an expiration. If the expiration (
events_expiry) is set to 1 day, this max value indicates that only 1000 events will be stored before dropping each day. In this case the limiting time is almost always the scheduled query. If a scheduled query that select from events-based tables occurs sooner than the expiration time that interval becomes the limit.
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 (
Built-in options include: filesystem, tls, syslog
Disable ERROR/WARNING/INFO (called status logs) and query result logging.
Log scheduled results as events.
Field used to identify the host running osquery (hostname, uuid)
Select either "hostname" or "uuid" for the host identifier. DHCP may assign variable hostnames, if this is the case, select UUID for a consistant logging label.
Enable verbose informational messages.
Directory path for ERROR/WARN/INFO and results logging.
File mode for output log files (provided as an octal string). Note that this affects both the query result log and the status logs. Warning: If run as root, log files may contain sensitive information!
Maximum returned row value size.
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 queries functionality. By default, this is set to
true (the distributed feature is disabled). Set this to
false to enable distributed queries.
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.
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:
--csv. For all of the output types there is
--separator that can be used appropriately.
When prototyping new queries the planner enables verbose decisions made by the SQLites virtual table API module. This module is implemented by osquery code so it is very helpful to learn what predicate constraints are selected and what full table scans are required for JOINs and nested queries.
Set this value to
false to disable column name (header) output. If using the shell in an automation or script the header line in
csv mode may not be needed.