remote_syslog2

remote_syslog tails one or more log files and sends syslog messages to a remote central syslog server. It generates packets itself, ignoring the system syslog daemon, so its configuration doesn't affect system-wide logging.

Uses:

• Collecting logs from servers & daemons which don't natively support syslog
• When reconfiguring the system logger is less convenient than a purpose-built daemon (e.g., automated app deployments)
• Aggregating files not generated by daemons (e.g., package manager logs)

This code is tested with the hosted log management servicePapertrail and should work for transmitting to any syslog server.

Migrating from remote_syslog 1

remote_syslog2 is a rewrite of the rubyremote_syslogpackage. Not all features of the ruby version are supported, and there are some backwards incompatible changes.

Which should I use?

Use remote_syslog2 (this README and application) unless you have a specific reason to use remote_syslog1.

Changes from remote_syslog 1

• The syntax of some command-line arguments have changed slightly, though most are identical.
• Default hostname has been removed. Either thehostconfig file option or the-dinvocation flag are required.

Installing

Precompiled binaries for Mac (Darwin), Linux and Windows are available on the remote_syslog2 releases page.

Untar the package, copy the "remote_syslog" executable into your $PATH, and then customize the included example_config.yml with the log file paths to read and the host/port to log to.

Optionally, move and rename the configuration file to/etc/log_files.ymlso that remote_syslog picks it up automatically. For example:

sudo cp./remote_syslog /usr/local/bin
sudo cp example_config.yml /etc/log_files.yml
sudo vi /etc/log_files.yml

Configuration directives can also be specified as command-line arguments (below).

Usage

Usage of remote_syslog2:
-c, --configfile string Path to config (default "/etc/log_files.yml" )
--debug-log-cfg string The debug log file; overridden by -D/--no-detach
-d, --dest-host string Destination syslog hostname or IP
-p, --dest-port int Destination syslog port (default 514)
-t, --dest-token string Destination ingestion token
--eventmachine-tail No action, provided for backwards compatibility
-f, --facility string Facility (default "user" )
-h, --help Display this help message
--hostname string Local hostname to send from (default: OS hostname)
--log string Set loggo config, like: --log= "<root>=DEBUG" (default "<root>=INFO" )
--new-file-check-interval int How often to check for new files (seconds) (default 10)
-D, --no-detach Don't daemonize and detach from the terminal; overrides --debug-log-cfg
--no-eventmachine-tail No action, provided for backwards compatibility
--pid-file string Location of the PID file
--poll Detect changes by polling instead of inotify
-s, --severity string Severity (default "notice" )
--tcp Connect via TCP (no TLS)
--tls Connect via TCP with TLS
-V, --version Display version and exit

Example

Daemonize and collect messages from files listed in./example_config.ymlas well as the file/var/log/mysqld.log.Write PID to/tmp/remote_syslog.pid and send to portlogs.papertrailapp:12345:

$ remote_syslog -c example_config.yml -p 12345 --pid-file=/tmp/remote_syslog.pid /var/log/mysqld.log

Stay attached to the terminal, look for and use/etc/log_files.ymlif it exists, and send with facility local0 toa.example:514:

$ remote_syslog -D -d a.example -f local0 /var/log/mysqld.log

Auto-starting at boot

Sample init files can be foundin the examples directory.You may be able to:

$ cp examples/remote_syslog.init.d /etc/init.d/remote_syslog
$ chmod 755 /etc/init.d/remote_syslog

And then ensure it's started at boot, either by using:

$ sudo update-rc.d remote_syslog defaults

or by creating a link manually:

$ sudo ln -s /etc/init.d/remote_syslog /etc/rc3.d/S30remote_syslog

remote_syslog will daemonize by default.

Additional information about init files (init.d,supervisor,systemdandupstart) are availablein the examples directory.

Sending messages securely

If the receiving system supports sending syslog over TCP with TLS, you can pass the--tlsoption when runningremote_syslog:

$ remote_syslog -D --tls -p 1234 /var/log/mysqld.log

or addprotocol: tlsto your configuration file.

Configuration

By default, remote_syslog looks for a configuration in/etc/log_files.yml.

The archive comes with asample config.Optionally:

$ cp example_config.yml.example /etc/log_files.yml

log_files.ymlhas filenames to log from (as an array) and hostname and port to log to (as a hash). Wildcards are supported using * and standard shell globbing. Filenames given on the command line are additive to those in the config file.

Only 1 destination server is supported; the command-line argument wins.

files:
- /var/log/httpd/access_log
- /var/log/httpd/error_log
- /var/log/mysqld.log
- /var/run/mysqld/mysqld-slow.log
destination:
host: logs.papertrailapp
port: 12345
protocol: tls

remote_syslog sends the name of the file without a path ( "mysqld.log" ) as the syslog tag (program name).

After changing the configuration file, restartremote_syslogusing the init script or by manually killing and restarting the process. For example:

/etc/init.d/remote_syslog restart

Advanced Configuration (Optional)

Here's anadvanced configwhich uses all options.

Override hostname

Provide--hostname somehostnameor use thehostnameconfiguration option:

hostname: somehostname

Detecting new files

remote_syslog automatically detects and activates new log files that match its file specifiers. For example,*.logmay be provided as a file specifier, and remote_syslog will detect asome.logfile created after it was started.

By default, globs are re-checked every 10 seconds. To check for new files more frequently, use the--new-file-check-intervalargument. For example, to recheck globs every 1 second, use:

--new-file-check-interval 1

Note: messages may be written to new files in the period between when the file is created and when the periodic glob check detects it. This data is not transmitted.

If globs are specified on the command-line, enclose each one in single-quotes ('*.log') so the shell passes the raw glob string to remote_syslog (rather than the current set of matches). This is not necessary for globs defined in the config file.

Log rotation and the behavior of remote_syslog

External log rotation scripts often move or remove an existing log file and replace it with a new one (at a new inode). The Linux standard script logrotatesupports acopytruncateconfig option. With that option,logrotatewill copy files, operate on the copies, and truncate the original so that the inode remains the same.

remote_syslogwill handle both approaches seamlessly, so it should be no concern as to which method is used. If a log file is moved or renamed, and a new file is created (at a new inode),remote_syslogwill follow that new file at the new inode (assuming it has the same absolute path name). If a file is copied then truncated,remote_syslogwill seek to the beginning of the truncated file and continue to read it.

Log rotation edge cases to be aware of

Some logging programs such as Java's gclog (-XX:+PrintGCor-verbose:gc) do not log in append mode, so if another program such aslogrotate(set to copytruncate) truncates the file, on the next write of the Java logger, the OS will fill the file with NUL bytes upto the current offset of the file descriptor. More info on thathere. remote_syslogwill detect those leading NUL bytes, discard them, and log the discard count.

Excluding files from being sent

Provide one or more regular expressions to prevent certain files from being matched.

exclude_files:
- \.\d$
-.bz2
-.gz

Excluding lines matching a pattern

There may be certain log messages that you do not want to be sent. These may be repetitive log lines that are "noise" that you might not be able to filter out easily from the respective application. To filter these lines, use the exclude_patterns with an array or regexes:

exclude_patterns:
- exclude this
- \d+ things

Multiple instances

Run multiple instances to specify unique syslog hostnames.

To do that, provide an alternate PID path as a command-line option to the additional instance(s). For example:

--pid-file=/var/run/remote_syslog_2.pid

Note: Daemonized programs use PID files to identify whether the program is already running (more). Like other daemons, remote_syslog will refuse to run as a daemon (the default mode) when a PID file is present. If a.pid file is present but the daemon is not actually running, remove the PID file.

Choosing app name

remote_syslog uses the log file name (like "access_log" ) as the syslog program name, or what the syslog RFCs call the "tag." This is ideal unless remote_syslog watches many files that have the same name.

In that case, tell remote_syslog to set another program name using the tagattribute in the configuration file:

files:
- path: /var/log/httpd/access_log
tag: apache
destination:
host: logs.papertrailapp
port: 12345
protocol: tls

... or on the command line: remote_syslog apache=/var/log/httpd/access_log

This functionality was introduced in version 0.17

Troubleshooting

Generate debug log

To output debugging events with maximum verbosity, run:

remote_syslog --debug-log-cfg=logfile.txt --log= "<root>=DEBUG"

.. as well as any other arguments which are used in normal operation. This will setloggo's root logger to theDEBUGlevel and output tologfile.txt.

Truncated messages

To send messages longer than 1024 characters, use TCP (either TLS or cleartext TCP) instead of UDP. See "Sending messages securely"to use TCP with TLS for messages of any length.

Here's whylonger UDP messages are impossible to send over the Internet.

inotify

When running remote_syslog in the foreground using the-Dswitch, if you receive the error:

Error creating fsnotify watcher: inotify_init: too many open files

determine the maximum number of inotify instances that can be created using:

cat /proc/sys/fs/inotify/max_user_instances

and then increase this limit using:

echo VALUE >> /proc/sys/fs/inotify/max_user_instances

where VALUE is greater than the present setting. Confirm that remote_syslog starts up and then apply this new value permanently by adding the following to /etc/sysctl.conf::

fs.inotify.max_user_instances = VALUE

"No space left on device"

When monitoring a large number of files, this error may occur:

FATAL -- Error watching /path/here: no space left on device

To solve this, determine the maximum number of user watches that can be created using:

cat /proc/sys/fs/inotify/max_user_watches

and then increase them using:

echo VALUE >> /proc/sys/fs/inotify/max_user_watches

Once again, confirm that remote_syslog starts and then apply this value permanently by adding the following to/etc/sysctl.conf::

fs.inotify.max_user_watches = VALUE

Credits

• Paul Morton
• Papertrailstaff
• Paul Hammond

Reporting bugs

1. See whether the issue has already been reported:https://github /papertrail/remote_syslog2/issues/
2. If you don't find one, create an issue with a repro case.

Development

remote_syslog2 is written in go. To get everything set up, install gothen run:

go install github /mitchellh/gox
git clone git@github:papertrail/remote_syslog2.git

To run tests:

# run all tests
go test./...
# run all tests except the slower syslog reconnection tests
go test -short./...

Building

make

ARM support

As of 0.18, we introduced ARM support for remote_syslog2. Current ARM builds support all ARM platforms with hardware floating point instruction sets. This includes All Raspberry PI devices, most ARMv6 chips (Cortex), and ARMv7 and beyond.

Contributing

Once you've made your great commits:

1. Forkremote_syslog
2. Create a topic branch -git checkout -b my_branch
3. Commit the changes without changing the Rakefile or other files unrelated to your enhancement.
4. Push to your branch -git push origin my_branch
5. Create a Pull Request or anIssuewith a link to your branch
6. That's it!