osquery 1.7.3 introduced support for consuming and querying the Mac OSX system log via Apple System Log (ASL). osquery 1.7.4 introduced support for the Linux syslog via rsyslog. This document explains how to configure and use these syslog tables.
OS X Syslog
On Mac OSX, the
asl virtual table makes use of Apple's ASL store, querying this structured store using the routines provided in
No configuration is required to begin using the
asl table. Note, however, that the table is only able to query logs that are available in the ASL store.
If your target logs are not already being sent to the ASL store by your current configuration, take a look at the man page for
asl.conf, and use the
store action to ensure your logs of interest are available in the store.
asl.conf is also responsible for the rotation and retention settings of the ASL store.
Note: the configuration for
/var/log/commerce.log is hardcoded into the Apple provided syslog binaries, and we are not aware of a way to configure ASL to send these logs to the store.
asl table can be queried like any other osquery table. It exposes many of the columns of structured data from the ASL store, and other additional columns are made available as a JSON dictionary in the
extra column. Use
.schema asl in the
osqueryi shell to see the schema.
Basic query predicates (
>) are able to be efficiently queried in the store. The
LIKE predicate is also supported, however it must be tested after applying all othe predicates and reading logs from the store. For performance reasons, it is suggested to use at least one basic predicate in a query against the
asl table. For example,
select time, message from asl where facility = 'authpriv' and sender = 'sudo' and message like '%python%';
On Linux, the
syslog table queries logs forwarded over a named pipe from a properly configured rsyslogd. This method was chosen to support the widest range of Linux flavors (in theory, anything running at least rsyslogd version 5, and tested with Ubuntu 12/14, CentOS 7.1, RHEL 7.2), and to ensure that existing syslog routines and configurations are not modified. As syslog is ingested into osquery, it is written into the backing store (RocksDB) and made available for querying.
Note: the Syslog ingestion is NOT recommended for hosts functioning as syslog aggregators. We have not tested ingestion for massive-throughput or lossless setups.
syslog table requires additional configuration before it can be used. Append
--enable_syslog to your command line arguments or
--flagfile to enable osquery's
syslog event publisher thread.
When an osquery process that supports the
syslog table starts up, it will attempt to create (and properly set permissions for) a named pipe for rsyslogd to write to. The path for this pipe is determined by the configuration flag
--syslog_pipe_path (defaults to
/var/osquery/syslog_pipe). If verbose logging is turned on, you should see a status message indicating whether osquery was able to successfully open the pipe for reading.
Permissions for the pipe must at least allow rsyslogd to read/write, and osquery to read. For security, it is advised that the least possible privileges are enabled to allow this.
Once the named pipe is created, rsyslogd must be configured to write logs to the pipe. Add the following to your rsyslog configuration files (usually located in
rsyslog versions < 7
$template OsqueryCsvFormat, "%timestamp:::date-rfc3339,csv%,%hostname:::csv%,%syslogseverity:::csv%,%syslogfacility-text:::csv%,%syslogtag:::csv%,%msg:::csv%\n" *.* |/var/osquery/syslog_pipe;OsqueryCsvFormat
rsyslog versions >= 7
Note: the above configuration should also work, but rsyslog strongly recommends using the new style configuration syntax.
template( name="OsqueryCsvFormat" type="string" string="%timestamp:::date-rfc3339,csv%,%hostname:::csv%,%syslogseverity:::csv%,%syslogfacility-text:::csv%,%syslogtag:::csv%,%msg:::csv%\n" ) *.* action(type="ompipe" Pipe="/var/osquery/syslog_pipe" template="OsqueryCsvFormat")
rsyslogd must be restarted for the changes to take effect. On many systems, this can be achieved by
sudo service rsyslog restart.
Note: rsyslogd will only check once, at startup, whether it can write to the pipe. If rsyslogd cannot write to the pipe, it will not retry until restart.
Configuration flags control the retention of syslog logs.
--syslog_events_expiry (default 30 days) defines how long (in seconds) to keep logs.
--syslog_events_max (default 100,000) sets a maximum number of logs to retain (oldest logs are deleted first if this number is surpassed).
Once configuration is complete, the
syslog table can be queried like any other osquery table. It's schema can be viewed with
Note: only logs produced after this table was properly configured (and while osquery is running) will be available for querying.
If no logs are available to query, try turning on verbose logging, and see issue #1964 for debugging suggestions.