path: root/upstream/fedora-rawhide/man8/systemd-journal-remote.service.8

'\" t
.TH "SYSTEMD\-JOURNAL\-REMOTE\&.SERVICE" "8" "" "systemd 255" "systemd-journal-remote.service"
.\" -----------------------------------------------------------------
.\" * 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.service, systemd-journal-remote.socket, systemd-journal-remote \- Receive journal messages over the network
.SH "SYNOPSIS"
.PP
systemd\-journal\-remote\&.service
.PP
systemd\-journal\-remote\&.socket
.HP \w'\fB/usr/lib/systemd/systemd\-journal\-remote\fR\ 'u
\fB/usr/lib/systemd/systemd\-journal\-remote\fR [OPTIONS...] [\-o/\-\-output=\fIDIR\fR|\fIFILE\fR] [SOURCES...]
.SH "DESCRIPTION"
.PP
\fBsystemd\-journal\-remote\fR
is a command to receive serialized journal events and store them to journal files\&. 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\&.
.PP
systemd\-journal\-remote\&.service
is a system service that uses
\fBsystemd\-journal\-remote\fR
to listen for connections\&.
systemd\-journal\-remote\&.socket
configures the network address that
systemd\-journal\-remote\&.service
listens on\&. By default this is port 19532\&. What connections are accepted and how the received data is stored can be configured through the
\fBjournal-remote.conf\fR(5)
configuration file\&.
.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
[SOURCES...]
.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\&.
.sp
Added in version 239\&.
.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\&. http://some\&.host:19531/ or https://some\&.host:19531/\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-getter=\*(Aq\fR\fB\fIPROG\fR\fR\fB \fR\fB[OPTIONS...]\fR\fB\*(Aq\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
.\}
.sp
Added in version 239\&.
.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\&.
.sp
Added in version 239\&.
.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, the server listens on port 19532 by default, and the 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\&. Currently, only POST requests to
/upload
with
"Content\-Type: application/vnd\&.fdo\&.journal"
are supported\&.
.sp
Added in version 239\&.
.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\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-key=\fR
.RS 4
Takes a path to a SSL secret key file in PEM format\&. Defaults to
/etc/ssl/private/journal\-remote\&.pem\&. This option can be used with
\fB\-\-listen\-https=\fR\&. If the path refers to an
\fBAF_UNIX\fR
stream socket in the file system a connection is made to it and the key read from it\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-cert=\fR
.RS 4
Takes a path to a SSL certificate file in PEM format\&. Defaults to
/etc/ssl/certs/journal\-remote\&.pem\&. This option can be used with
\fB\-\-listen\-https=\fR\&. If the path refers to an
\fBAF_UNIX\fR
stream socket in the file system a connection is made to it and the certificate read from it\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-trust=\fR
.RS 4
Takes a path to a SSL CA certificate file in PEM format, or
\fBall\fR\&. If
\fBall\fR
is set, then certificate checking will be disabled\&. Defaults to
/etc/ssl/ca/trusted\&.pem\&. This option can be used with
\fB\-\-listen\-https=\fR\&. If the path refers to an
\fBAF_UNIX\fR
stream socket in the file system a connection is made to it and the certificate read from it\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-gnutls\-log=\fR
.RS 4
Takes a comma separated list of gnutls logging categories\&. This option can be used with
\fB\-\-listen\-http=\fR
or
\fB\-\-listen\-https=\fR\&.
.sp
Added in version 239\&.
.RE
.SH "SINKS"
.PP
The location of the output journal can be specified with
\fB\-o\fR
or
\fB\-\-output=\fR\&.
.PP
\fB\-o \fR\fB\fIFILE\fR\fR, \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\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-o \fR\fB\fIDIR\fR\fR, \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\&.
.sp
Added in version 239\&.
.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 the case that "active" sources are given by the positional arguments or
\fB\-\-getter=\fR
option, 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 the case that "active" sources are given by the positional arguments or
\fB\-\-getter=\fR
option, the output file name must always be given explicitly and only
\fBnone\fR
is allowed\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-compress\fR [\fIBOOL\fR]
.RS 4
If this is set to
"yes"
then compress the data in the journal using XZ\&. The default is
"yes"\&.
.sp
Added in version 239\&.
.RE
.PP
\fB\-\-seal\fR [\fIBOOL\fR]
.RS 4
If this is set to
"yes"
then periodically sign the data in the journal using Forward Secure Sealing\&. The default is
"no"\&.
.sp
Added in version 239\&.
.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/foo\&.journal \-
    
.fi
.if n \{\
.RE
.\}
.PP
Retrieve all available events from a remote
\fBsystemd-journal-gatewayd\fR(8)
instance and store them in
/var/log/journal/remote/remote\-some\&.host\&.journal:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\-journal\-remote \-\-url http://some\&.host:19531/
    
.fi
.if n \{\
.RE
.\}
.PP
Retrieve current boot events and wait for new events from a remote
\fBsystemd-journal-gatewayd\fR(8)
instance, and store them in
/var/log/journal/remote/remote\-some\&.host\&.journal:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\-journal\-remote \-\-url http://some\&.host:19531/entries?boot&follow
    
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBjournal-remote.conf\fR(5),
\fBjournalctl\fR(1),
\fBsystemd-journal-gatewayd.service\fR(8),
\fBsystemd-journal-upload.service\fR(8),
\fBsystemd-journald.service\fR(8)
.SH "NOTES"
.IP " 1." 4
Journal Export Format
.RS 4
\%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
.RE