systemd/man/systemd-journal-remote.8

'\" t
.TH "SYSTEMD\-JOURNAL\-REMOTE" "8" "" "systemd 219" "systemd-journal-remote"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-journal-remote \- Receive journal messages over the network
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-journal\-remote\fR\ 'u
\fBsystemd\-journal\-remote\fR [OPTIONS...] [\-o/\-\-output=\fIDIR\fR|\fIFILE\fR] [SOURCES...]
.SH "DESCRIPTION"
.PP
systemd\-journal\-remote
is a command to receive serialized journal events and store them to the journal\&. Input streams are in the
\m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[1]\d\s+2, i\&.e\&. like the output from
\fBjournalctl \-\-output=export\fR\&. For transport over the network, this serialized stream is usually carried over an HTTPS connection\&.
.SH "SOURCES"
.PP
Sources can be either "active" (\fBsystemd\-journal\-remote\fR
requests and pulls the data), or "passive" (\fBsystemd\-journal\-remote\fR
waits for a connection and then receives events pushed by the other side)\&.
.PP
\fBsystemd\-journal\-remote\fR
can read more than one event stream at a time\&. They will be interleaved in the output file\&. In case of "active" connections, each "source" is one stream, and in case of "passive" connections, each connection can result in a separate stream\&. Sockets can be configured in "accept" mode (i\&.e\&. only one connection), or "listen" mode (i\&.e\&. multiple connections, each resulting in a stream)\&.
.PP
When there are no more connections, and no more can be created (there are no listening sockets), then
\fBsystemd\-journal\-remote\fR
will exit\&.
.PP
Active sources can be specified in the following ways:
.PP
.RS 4
When
\fB\-\fR
is given as a positional argument, events will be read from standard input\&. Other positional arguments will be treated as filenames to open and read from\&.
.RE
.PP
\fB\-\-url=\fR\fB\fIADDRESS\fR\fR
.RS 4
With the
\fB\-\-url=\fR\fB\fIADDRESS\fR\fR
option, events will be retrieved using HTTP from
\fIADDRESS\fR\&. This URL should refer to the root of a remote
\fBsystemd-journal-gatewayd\fR(8)
instance (e\&.g\&.
\m[blue]\fBhttp://some\&.host:19531/\fR\m[]
or
\m[blue]\fBhttps://some\&.host:19531/\fR\m[])\&.
.RE
.PP
Passive sources can be specified in the following ways:
.PP
\fB\-\-listen\-raw=\fR\fB\fIADDRESS\fR\fR
.RS 4
\fIADDRESS\fR
must be an address suitable for
\fBListenStream=\fR
(cf\&.
\fBsystemd.socket\fR(5))\&.
\fBsystemd\-journal\-remote\fR
will listen on this socket for connections\&. Each connection is expected to be a stream of journal events\&.
.RE
.PP
\fB\-\-listen\-http=\fR\fB\fIADDRESS\fR\fR, \fB\-\-listen\-https=\fR\fB\fIADDRESS\fR\fR
.RS 4
\fIADDRESS\fR
must be either a negative integer, in which case it will be interpreted as the (negated) file descriptor number, or an address suitable for
\fBListenStream=\fR
(c\&.f\&.
\fBsystemd.socket\fR(5))\&. In the first case, matching file descriptor must be inherited through
\fI$LISTEN_FDS\fR/\fI$LISTEN_PID\fR\&. In the second case, an HTTP or HTTPS server will be spawned on this port, respectively for
\fB\-\-listen\-http\fR
and
\fB\-\-listen\-https\fR\&. Currenntly, only POST requests to
/upload
with
"Content\-Type: application/vnd\&.fdo\&.journal"
are supported\&.
.RE
.PP
\fI$LISTEN_FDS\fR
.RS 4
\fBsystemd\-journal\-remote\fR
supports the
\fI$LISTEN_FDS\fR/\fI$LISTEN_PID\fR
protocol\&. Open sockets inherited through socket activation behave like those opened with
\fB\-\-listen\-raw=\fR
described above, unless they are specified as an argument in
\fB\-\-listen\-http=\-\fR\fB\fIn\fR\fR
or
\fB\-\-listen\-https=\-\fR\fB\fIn\fR\fR
above\&. In the latter case, an HTTP or HTTPS server will be spawned using this descriptor and connections must be made over the HTTP protocol\&.
.RE
.SH "SINKS"
.PP
The location of the output journal can be specified with
\fB\-o\fR
or
\fB\-\-output=\fR\&. For "active" sources, this option is required\&.
.PP
\fB\-\-output=\fR\fB\fIFILE\fR\fR
.RS 4
Will write to this journal file\&. The filename must end with
\&.journal\&. The file will be created if it does not exist\&. If necessary (journal file full, or corrupted), the file will be renamed following normal journald rules and a new journal file will be created in its stead\&.
.RE
.PP
\fB\-\-output=\fR\fB\fIDIR\fR\fR
.RS 4
Will create journal files underneath directory
\fIDIR\fR\&. The directory must exist\&. If necessary (journal files over size, or corrupted), journal files will be rotated following normal journald rules\&. Names of files underneath
\fIDIR\fR
will be generated using the rules described below\&.
.RE
.PP
If
\fB\-\-output=\fR
is not used, the output directory
/var/log/journal/remote/
will be used\&. In case the output file is not specified, journal files will be created underneath the selected directory\&. Files will be called
remote\-\fIhostname\fR\&.journal, where the
\fIhostname\fR
part is the escaped hostname of the source endpoint of the connection, or the numerical address if the hostname cannot be determined\&.
.PP
In case of "active" sources, the output file name must always be given explicitly\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-split\-mode\fR
.RS 4
One of
\fBnone\fR
or
\fBhost\fR\&. For the first, only one output journal file is used\&. For the latter, a separate output file is used, based on the hostname of the other endpoint of a connection\&.
.sp
In case of "active" sources, the output file name must always be given explicitly and only
\fBnone\fR
is allowed\&.
.RE
.PP
\fB\-\-compress\fR, \fB\-\-no\-compress\fR
.RS 4
Compress or not, respectively, the data in the journal using XZ\&.
.RE
.PP
\fB\-\-seal\fR, \fB\-\-no\-seal\fR
.RS 4
Periodically sign or not, respectively, the data in the journal using Forward Secure Sealing\&.
.RE
.PP
\fB\-\-getter=\fR\fB\fIPROG \-\-option1 \-\-option2\fR\fR
.RS 4
Program to invoke to retrieve data\&. The journal event stream must be generated on standard output\&.
.sp
Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-getter=\*(Aqcurl "\-HAccept: application/vnd\&.fdo\&.journal" https://some\&.host:19531/\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-getter=\*(Aqwget \-\-header="Accept: application/vnd\&.fdo\&.journal" \-O\- https://some\&.host:19531/\*(Aq
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SH "EXAMPLES"
.PP
Copy local journal events to a different journal directory:
.sp
.if n \{\
.RS 4
.\}
.nf
journalctl \-o export | systemd\-journal\-remote \-o /tmp/dir \-
    
.fi
.if n \{\
.RE
.\}
.PP
Retrieve events from a remote
\fBsystemd-journal-gatewayd\fR(8)
instance and store them in
/var/log/journal/some\&.host/remote\-some~host\&.journal:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\-journal\-remote \-\-url http://some\&.host:19531/
    
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBsystemd-journal-upload\fR(8),
\fBjournalctl\fR(1),
\fBsystemd-journald.service\fR(8),
\fBsystemd-journal-gatewayd.service\fR(8)
.SH "NOTES"
.IP " 1." 4
Journal Export Format
.RS 4
\%http://www.freedesktop.org/wiki/Software/systemd/export
.RE
.IP " 2." 4
http://some.host:19531/
.IP " 3." 4
https://some.host:19531/