.D........ [ZBX-9347] add information about zabbix_sender input file format to the man page

[svn merge -c r56247 ^/branches/2.4]

1 files changed, 63 insertions, 23 deletions

diff --git a/man/zabbix_sender.man b/man/zabbix_sender.man
index a0a6a7f0ccd..9a066f5582f 100644
--- a/man/zabbix_sender.man
+++ b/man/zabbix_sender.man
@@ -1,4 +1,4 @@
-.TH ZABBIX_SENDER 1 "2015\-08\-06" Zabbix
+.TH ZABBIX_SENDER 1 "2015\-10\-16" Zabbix
 .if n .ad l
 .SH NAME
 zabbix_sender \- Zabbix sender utility
@@ -314,15 +314,55 @@ Specify item key to send value to.
 Specify item value.
 .IP "\fB\-i\fR, \fB\-\-input\-file\fR \fIinput\-file\fR"
 Load values from input file.
-Specify \fB\-\fR for standard input.
+Specify \fB\-\fR as \fB<input-file>\fR to read values from standard input.
 Each line of file contains whitespace delimited: \fB<hostname> <key> <value>\fR.
-Specify \fB\-\fR in \fB<hostname>\fR to use hostname from configuration file or \fB\-\-host\fR argument.
-All entries are sent in a sequential order top\-down.
+Each value must be specified on its own line.  Each line must contain 3 whitespace delimited entries:
+\fB<hostname> <key> <value>\fR, where "hostname" is the name of monitored host as registered in Zabbix frontend,
+"key" is target item key and "value" \- the value to send. Specify \fB-\fR as \fB<hostname>\fR to use hostname from
+agent configuration file or from \fB\-\-host\fR argument.
+
+An example of a line of an input file:
+
+\fB "Linux DB3" db.connections 43\fR
+
+The value type must be correctly set in item configuration of Zabbix frontend.
+Zabbix sender will send up to 250 values in one connection.
+Contents of the input file must be in the UTF\-8 encoding.
+All values from the input file are sent in a sequential order top\-down.
+Entries must be formatted using the following rules:
+
+.RS
+.RS
+.IP \[bu] 2
+Quoted and non-quoted entries are supported.
+.IP \[bu]
+Double-quote is the quoting character.
+.IP \[bu]
+Entries with whitespace must be quoted.
+.IP \[bu]
+Double-quote and backslash characters inside quoted entry must be escaped with a backslash.
+.IP \[bu]
+Escaping is not supported in non-quoted entries.
+.IP \[bu]
+Linefeed escape sequences (\\n) are supported in quoted strings.
+.IP \[bu]
+Linefeed escape sequences are trimmed from the end of an entry.
+.RE
+.RE
+
 .IP "\fB\-T\fR, \fB\-\-with\-timestamps\fR"
-Each line of file contains whitespace delimited: \fB<hostname> <key> <timestamp> <value>\fR.
-This can be used with \fB\-\-input\-file\fR option.
+This option can be only used with \fB\-\-input\-file\fR option.
+
+Each line of the input file must contain 4 whitespace delimited entries: \fB<hostname> <key> <timestamp> <value>\fR.
 Timestamp should be specified in Unix timestamp format.
 If target item has triggers referencing it, all timestamps must be in an increasing order, otherwise event calculation will not be correct.
+
+An example of a line of the input file:
+
+\fB "Linux DB3" db.connections 1429533600 43\fR
+
+For more details please see option \fB\-\-input\-file\fR.
+
 .IP "\fB\-r\fR, \fB\-\-real\-time\fR"
 Send values one by one as soon as they are received.
 This can be used when reading from standard input.
@@ -377,32 +417,20 @@ If data sending failed, the exit status is 1.
 \fBzabbix_sender \-c /usr/local/etc/zabbix_agentd.conf \-k mysql.queries \-o 342.45\fR
 .br
 .RS
-Send \fB342.45\fR as the value for \fBmysql.queries\fR item of monitored host. Use monitored host and Zabbix server defined in agent daemon configuration file.
-.RE
-
-\fBzabbix_sender \-c /usr/local/etc/zabbix_agentd.conf \-s "Monitored Host" \-k mysql.queries \-o 342.45\fR
-.br
-.RS
-Send \fB342.45\fR as the value for \fBmysql.queries\fR item in \fBMonitored Host\fR host using Zabbix server defined in agent daemon configuration file.
-.RE
-
-\fBzabbix_sender \-z 192.168.1.113  \-s "Monitored Host" \-k mysql.queries \-o 342.45 \-\-tls\-connect cert \-\-tls\-ca\-file /home/zabbix/zabbix_ca_file \-\-tls\-cert\-file /home/zabbix/zabbix_agentd.crt \-\-tls\-key\-file /home/zabbix/zabbix_agentd.key\fR
-.br
-.RS
-Send \fB342.45\fR as the value for \fBmysql.queries\fR item in \fBMonitored Host\fR host to server with IP \fB192.168.1.113\fR using TLS with certificate.
+Send \fB342.45\fR as the value for \fBmysql.queries\fR item of monitored host. Use monitored host and Zabbix server defined in agent configuration file.
 .RE
 
-\fBzabbix_sender \-z 192.168.1.113  \-s "Monitored Host" \-k mysql.queries \-o 342.45 \-\-tls\-connect psk \-\-tls\-psk\-identity "PSK ID Zabbix agentd" \-\-tls\-psk\-file /home/zabbix/zabbix_agentd.psk\fR
+\fBzabbix_sender \-c /etc/zabbix/zabbix_agentd.conf \-s "Monitored Host" \-k mysql.queries \-o 342.45\fR
 .br
 .RS
-Send \fB342.45\fR as the value for \fBmysql.queries\fR item in \fBMonitored Host\fR host to server with IP \fB192.168.1.113\fR using TLS with pre-shared key (PSK).
+Send \fB342.45\fR as the value for \fBmysql.queries\fR item of \fBMonitored Host\fR host using Zabbix server defined in agent configuration file.
 .RE
 
 .br
 \fBzabbix_sender \-z 192.168.1.113 \-i data_values.txt\fR
 .RS
 .br
-Send values from file \fBdata_values.txt\fR to server with IP \fB192.168.1.113\fR.
+Send values from file \fBdata_values.txt\fR to Zabbix server with IP \fB192.168.1.113\fR.
 Host names and keys are defined in the file.
 .RE
 
@@ -410,7 +438,7 @@ Host names and keys are defined in the file.
 \fBecho "\- hw.serial.number 1287872261 SQ4321ASDF" | zabbix_sender \-c /usr/local/etc/zabbix_agentd.conf \-T \-i \-\fR
 .br
 .RS
-Send a timestamped value from the commandline to Zabbix server, specified in the agent daemon configuration file.
+Send a timestamped value from the commandline to Zabbix server, specified in the agent configuration file.
 Dash in the input data indicates that hostname also should be used from the same configuration file.
 .RE
 
@@ -422,6 +450,18 @@ Send empty value of an item to the Zabbix server with IP address \fB192.168.1.11
 Empty values must be indicated by empty double quotes.
 .RE
 
+\fBzabbix_sender \-z 192.168.1.113  \-s "Monitored Host" \-k mysql.queries \-o 342.45 \-\-tls\-connect cert \-\-tls\-ca\-file /home/zabbix/zabbix_ca_file \-\-tls\-cert\-file /home/zabbix/zabbix_agentd.crt \-\-tls\-key\-file /home/zabbix/zabbix_agentd.key\fR
+.br
+.RS
+Send \fB342.45\fR as the value for \fBmysql.queries\fR item in \fBMonitored Host\fR host to server with IP \fB192.168.1.113\fR using TLS with certificate.
+.RE
+
+\fBzabbix_sender \-z 192.168.1.113  \-s "Monitored Host" \-k mysql.queries \-o 342.45 \-\-tls\-connect psk \-\-tls\-psk\-identity "PSK ID Zabbix agentd" \-\-tls\-psk\-file /home/zabbix/zabbix_agentd.psk\fR
+.br
+.RS
+Send \fB342.45\fR as the value for \fBmysql.queries\fR item in \fBMonitored Host\fR host to server with IP \fB192.168.1.113\fR using TLS with pre-shared key (PSK).
+.RE
+
 .SH "SEE ALSO"
 .BR zabbix_agentd (8),
 .BR zabbix_get (8),