Skip to content

Commit 86a75df

Browse files
czerwingithubczerwingithub
committed
Updated syslog documentation.
1 parent 4bbc37b commit 86a75df

File tree

2 files changed

+154
-140
lines changed

2 files changed

+154
-140
lines changed

‎docs/monitors/syslog_monitor.md‎

Lines changed: 80 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,103 @@
1-
Description:
1+
/// DECLARE path=/help/monitors/syslog-monitor
2+
/// DECLARE title=Syslog Monitor
3+
/// DECLARE section=help
4+
/// DECLARE subsection=monitors
25

36
# Syslog Monitor
47

5-
The Syslog monitor can receive log messages received via the syslog protocol over either syslog UDP or TCP/IP and
6-
upload them to Scalyr. This is useful for acting as a proxy between server applications that export their logs via
7-
syslog and Scalyr.
8+
The Syslog monitor allows the Scalyr Agent to act as a syslog server, proxying logs from any application or device
9+
that supports syslog. It can recieve log messages via the syslog TCP or syslog UDP protocols.
810

9-
The monitor accepts connections from the localhost (by default) and writes all received syslog messages to a single
10-
log file (defaulting to ``agentSyslog.log``) which is then copied to Scalyr. This log file is configured
11-
to be parsed using the ``agentSyslog`` parser. You may wish to edit this parser to parse the line according to your
12-
specific syslog message format.
11+
@class=bg-warning docInfoPanel: An *agent monitor plugin* is a component of the Scalyr Agent. To use a plugin,
12+
simply add it to the ``monitors`` section of the Scalyr Agent configuration file (``/etc/scalyr/agent.json``).
13+
For more information, see [Agent Plugins](/help/scalyr-agent#plugins).
1314

14-
## Configuring Scalyr Agent
1515

16-
In order to use this monitor, you will first need to enable it in your agent's ``agent.json`` configuration file and
17-
specify the protocol and ports to receive messages on. A typical configuration fragment is shown below:
16+
## Sample Configuration
1817

19-
monitors: [
20-
{
21-
module: "scalyr_agent.builtin_monitors.syslog_monitor",
22-
protocols: "tcp:601,udp:514"
23-
}
24-
]
18+
This sample will configure the agent to accept syslog messages on TCP port 601 and UDP port 514, from localhost
19+
only:
2520

26-
As the fragment demonstrates, you may listen on one or more protocol/port combinations using a comma-deliminated
27-
list. Only ``tcp`` or ``udp`` are allowed for the protocol specification, and any valid, unused port number is
28-
allowed for the port. Note, if you use ports 1024 or less on Linux, you must be sure your agent is running as root.
21+
monitors: [
22+
{
23+
module: "scalyr_agent.builtin_monitors.syslog_monitor",
24+
protocols: "tcp:601, udp:514",
25+
accept_remote_connections: false
26+
}
27+
]
2928

30-
You may wish to accept syslog connections from other hosts than just localhost. For example, you may have a
31-
network device that cannot run the agent itself, but does use syslog to export its log. You can configure
32-
the Syslog Monitor to accept non-localhost connections by setting the ``accept_remote_connections`` configuration option
33-
to true. Here is a sample fragment that demonstrates this:
29+
You can specify any number of protocol/port combinations. Note that on Linux, to use port numbers 1024 or lower,
30+
the agent must be running as root.
3431

35-
monitors: [
36-
{
37-
module: "scalyr_agent.builtin_monitors.syslog_monitor",
38-
protocols: "tcp:601,udp:514",
39-
accept_remote_connections: true
40-
}
41-
]
32+
You may wish to accept syslog connections from other devices on the network, such as a firewall or router which
33+
exports logs via syslog. Set ``accept_remote_connections`` to true to allow this.
4234

43-
See the options section below for more information about all of the available configuration options.
35+
Additional options are documented in the Configuration Reference section, below.
4436

45-
## Configuring syslog sources
4637

47-
After your agent is configured to accept syslog connections, you must then configure your log sources to send
48-
messages to it. If your application can send log messages directly, you will need to find instructions
49-
on how to configure the syslog destination. If you need help doing this, please feel free to e-mail
50-
``[email protected]`` for help.
38+
## Log files and parsers
39+
40+
By default, all syslog messages are written to a single log file, named ``agentSyslog.log``. You can use the
41+
``message_log`` option to specify a different file name (see Configuration Reference).
42+
43+
If you'd like to send messages from different devices to different log files, you can include multiple syslog_monitor
44+
stanzas in your configuration file. Specify a different ``message_log`` for each monitor, and have each listen on a
45+
different port number. Then configure each device to send to the appropriate port.
46+
47+
syslog_monitor logs use a parser named ``agentSyslog``. To set up parsing for your syslog messages, go to the
48+
[Parser Setup Page](/parsers?parser=agentSyslog) and click {{menuRef:Leave it to Us}} or
49+
{{menuRef:Build Parser By Hand}}. If you are using multiple syslog_monitor stanzas, you can specify a different
50+
parser for each one, using the ``parser`` option.
51+
52+
53+
## Sending messages via syslog
54+
55+
To send messages to the Scalyr Agent using the syslog protocol, you must configure your application or network
56+
device. The documentation for your application or device should include instructions. We'll be happy to help out;
57+
please drop us a line at [[email protected]](mailto:[email protected]).
58+
5159

5260
### Rsyslogd
5361

54-
Rsyslogd is a popular syslog server used on Linux machines. It uses a very rich configuration language that allows
55-
you to do complex operations with the syslog messages it receives, such as splitting them up into separate
56-
log files by their log type or sending them to another syslog server over TCP/IP or UDP.
62+
To send messages from another Linux host, you may wish to use the popular ``rsyslogd`` utility. rsyslogd has a
63+
powerful configuration language, and can be used to forward all logs or only a selected set of logs.
5764

58-
You may wish to configure rsyslogd to send a subset of the syslog messages generated by that server to
59-
Scalyr. There are many ways you can do this, but we will show you a simple example.
65+
Here is a simple example. Suppose you have configured Scalyr's Syslog Monitor to listen on TCP port 601, and you
66+
wish to use rsyslogd on the local host to upload system log messages of type ``authpriv``. You would add the following
67+
lines to your rsyslogd configuration, which is typically in ``/etc/rsyslogd.conf``:
6068

61-
Suppose you wish to send all log messages with type ``authpriv`` to a the Syslog Monitor running on localhost over
62-
TCP/IP using port 601. You would add the following lines to your rsyslogd configuration, which is typically stored
63-
in ``/etc/rsyslogd.conf``:
69+
# Send all authpriv messasges to Scalyr.
70+
authpriv.* @@localhost:601
6471

65-
# Send all authpriv messasges to Scalyr.
66-
authpriv.* @@localhost:601
72+
Make sure that this line comes before any other filters that could match the authpriv messages. The ``@@`` prefix
73+
specifies TCP.
74+
75+
76+
## Viewing Data
77+
78+
Messages uploaded by the Syslog Monitor will appear as an independent log file on the host where the agent is
79+
running. You can find this log file in the [Overview](/logStart) page. By default, the file is named "agentSyslog.log".
80+
81+
82+
## Configuration Reference
6783

68-
You must ensure that the line appears in the file before any other filters that could match the authpriv messages.
69-
Note, the ``@@`` prefix indicates TCP/IP should be used. A single ``@`` indicates UDP.
70-
71-
Options:
7284
|||# Option ||| Usage
7385
|||# ``module`` ||| Always ``scalyr_agent.builtin_monitors.syslog_monitor``
74-
|||# ``protocols`` ||| Optional (defaults to tcp). Defines which transport protocols and ports to \
75-
listen for syslog messages on. Valid values can be 'udp' or 'tcp', which can be \
76-
bare, e.g. 'udp' or combined with a port number, e.g. 'udp:10514'. Multiple \
77-
values can be combined with a comma to specify both, e.g. 'udp, tcp'. If no \
78-
port is specified, then 514 is used for 'udp' and 601 is used for 'tcp'.
86+
|||# ``protocols`` ||| Optional (defaults to ``tcp:601``). Lists the protocols and ports on which the \
87+
agent will accept messages. You can include one or more entries, separated by \
88+
commas. Each entry must be of the form ``tcp:NNN`` or ``udp:NNN``. Port \
89+
numbers are optional, defaulting to 601 for TCP and 514 for UDP.
7990
|||# ``accept_remote_connections``||| Optional (defaults to false). If true, the plugin will accept network \
80-
connections from any host, instead of just from localhost.
81-
|||# ``message_log`` ||| Optional (defaults to agent_syslog.log). Defines a log file name for storing \
82-
syslog messages that are received by the agent syslog monitor. Note: the file \
83-
will be placed in the default Scalyr log directory unless it is an absolute \
84-
path.
85-
|||# ``parser`` ||| Optional (defaults to agentSyslog). Defines the parser that should be specified \
86-
for the message_log file.
87-
|||# ``tcp_buffer_size`` ||| Optional (defaults to 8K). The maximum buffer size for a single TCP syslog \
88-
message. Note: RFC 5425 (syslog over TCP/TLS) says syslog receivers MUST be \
89-
able to support messages at least 2048 bytes long, and recommends they SHOULD \
90-
support messages up to 8192 bytes long.
91-
|||# ``max_log_size`` ||| Optional (defaults to 100 MB - 100*1024*1024). The maximum file size of the \
92-
syslog messages log before log rotation occurs. Set to zero for infinite size.
93-
|||# ``max_log_rotations`` ||| Optional (defaults to 5). The maximum number of log rotations before deleting \
94-
old logs. Set to zero for infinite rotations.
95-
96-
Log reference:
97-
|||# Field||| Meaning
98-
99-
Metrics:
100-
91+
connections from any host; otherwise, it will only accept connections from localhost.
92+
|||# ``message_log`` ||| Optional (defaults to ``agent_syslog.log``). Specifies the file name under which \
93+
syslog messages are stored. The file will be placed in the default Scalyr log \
94+
directory, unless it is an absolute path.
95+
|||# ``parser`` ||| Optional (defaults to ``agentSyslog``). Defines the parser name associated with \
96+
the log file.
97+
|||# ``max_log_size`` ||| Optional (defaults to 50 MB). How large the log file will grow before it is rotated. \
98+
Set to zero for infinite size. Note that rotation is not visible in Scalyr; it is \
99+
only relevant for managing disk space on the host running the agent. However, a \
100+
very small limit could cause logs to be dropped if there is a temporary network \
101+
outage and the log overflows before it can be sent to Scalyr.
102+
|||# ``max_log_rotations`` ||| Optional (defaults to 2). The maximum number of log rotations before older log \
103+
files are deleted. Set to zero for infinite rotations.

0 commit comments

Comments
 (0)