man/systemd-journal-remote.8

   1 '\" t
   2 .TH "SYSTEMD\-JOURNAL\-REMOTE" "8" "" "systemd 217" "systemd-journal-remote"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 systemd-journal-remote \- Receive journal messages over the network
  24 .SH "SYNOPSIS"
  25 .HP \w'\fBsystemd\-journal\-remote\fR\ 'u
  26 \fBsystemd\-journal\-remote\fR [OPTIONS...] [\-o/\-\-output=\fIDIR\fR|\fIFILE\fR] [SOURCES...]
  27 .SH "DESCRIPTION"
  28 .PP
  29 systemd\-journal\-remote
  30 is a command to receive serialized journal events and store them to the journal\&. Input streams are in the
  31 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[1]\d\s+2, i\&.e\&. like the output from
  32 \fBjournalctl \-\-output=export\fR\&. For transport over the network, this serialized stream is usually carried over an HTTPS connection\&.
  33 .SH "SOURCES"
  34 .PP
  35 Sources can be either "active" (\fBsystemd\-journal\-remote\fR
  36 requests and pulls the data), or "passive" (\fBsystemd\-journal\-remote\fR
  37 waits for a connection and then receives events pushed by the other side)\&.
  38 .PP
  39 \fBsystemd\-journal\-remote\fR
  40 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)\&.
  41 .PP
  42 When there are no more connections, and no more can be created (there are no listening sockets), then
  43 \fBsystemd\-journal\-remote\fR
  44 will exit\&.
  45 .PP
  46 Active sources can be specified in the following ways:
  47 .PP
  48 .RS 4
  49 When
  50 \fB\-\fR
  51 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\&.
  52 .RE
  53 .PP
  54 \fB\-\-url=\fR\fB\fIADDRESS\fR\fR
  55 .RS 4
  56 With the
  57 \fB\-\-url=\fR\fB\fIADDRESS\fR\fR
  58 option, events will be retrieved using HTTP from
  59 \fIADDRESS\fR\&. This URL should refer to the root of a remote
  60 \fBsystemd-journal-gatewayd\fR(8)
  61 instance (e\&.g\&.
  62 \m[blue]\fBhttp://some\&.host:19531/\fR\m[]
  63 or
  64 \m[blue]\fBhttps://some\&.host:19531/\fR\m[])\&.
  65 .RE
  66 .PP
  67 Passive sources can be specified in the following ways:
  68 .PP
  69 \fB\-\-listen\-raw=\fR\fB\fIADDRESS\fR\fR
  70 .RS 4
  71 \fIADDRESS\fR
  72 must be an address suitable for
  73 \fBListenStream=\fR
  74 (cf\&.
  75 \fBsystemd.socket\fR(5))\&.
  76 \fBsystemd\-journal\-remote\fR
  77 will listen on this socket for connections\&. Each connection is expected to be a stream of journal events\&.
  78 .RE
  79 .PP
  80 \fB\-\-listen\-http=\fR\fB\fIADDRESS\fR\fR, \fB\-\-listen\-https=\fR\fB\fIADDRESS\fR\fR
  81 .RS 4
  82 \fIADDRESS\fR
  83 must be either a negative integer, in which case it will be interpreted as the (negated) file descriptor number, or an address suitable for
  84 \fBListenStream=\fR
  85 (c\&.f\&.
  86 \fBsystemd.socket\fR(5))\&. In the first case, matching file descriptor must be inherited through
  87 \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
  88 \fB\-\-listen\-http\fR
  89 and
  90 \fB\-\-listen\-https\fR\&. Currenntly, only POST requests to
  91 /upload
  92 with
  93 "Content\-Type: application/vnd\&.fdo\&.journal"
  94 are supported\&.
  95 .RE
  96 .PP
  97 \fI$LISTEN_FDS\fR
  98 .RS 4
  99 \fBsystemd\-journal\-remote\fR
 100 supports the
 101 \fI$LISTEN_FDS\fR/\fI$LISTEN_PID\fR
 102 protocol\&. Open sockets inherited through socket activation behave like those opened with
 103 \fB\-\-listen\-raw=\fR
 104 described above, unless they are specified as an argument in
 105 \fB\-\-listen\-http=\-\fR\fB\fIn\fR\fR
 106 or
 107 \fB\-\-listen\-https=\-\fR\fB\fIn\fR\fR
 108 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\&.
 109 .RE
 110 .SH "SINKS"
 111 .PP
 112 The location of the output journal can be specified with
 113 \fB\-o\fR
 114 or
 115 \fB\-\-output=\fR\&. For "active" sources, this option is required\&.
 116 .PP
 117 \fB\-\-output=\fR\fB\fIFILE\fR\fR
 118 .RS 4
 119 Will write to this journal file\&. The filename must end with
 120 \&.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\&.
 121 .RE
 122 .PP
 123 \fB\-\-output=\fR\fB\fIDIR\fR\fR
 124 .RS 4
 125 Will create journal files underneath directory
 126 \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
 127 \fIDIR\fR
 128 will be generated using the rules described below\&.
 129 .RE
 130 .PP
 131 If
 132 \fB\-\-output=\fR
 133 is not used, the output directory
 134 /var/log/journal/remote/
 135 will be used\&. In case the output file is not specified, journal files will be created underneath the selected directory\&. Files will be called
 136 remote\-\fIhostname\fR\&.journal, where the
 137 \fIhostname\fR
 138 part is the escaped hostname of the source endpoint of the connection, or the numerical address if the hostname cannot be determined\&.
 139 .PP
 140 In case of "active" sources, the output file name must always be given explicitly\&.
 141 .SH "OPTIONS"
 142 .PP
 143 The following options are understood:
 144 .PP
 145 \fB\-\-split\-mode\fR
 146 .RS 4
 147 One of
 148 \fBnone\fR
 149 or
 150 \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\&.
 151 .sp
 152 In case of "active" sources, the output file name must always be given explicitly and only
 153 \fBnone\fR
 154 is allowed\&.
 155 .RE
 156 .PP
 157 \fB\-\-compress\fR, \fB\-\-no\-compress\fR
 158 .RS 4
 159 Compress or not, respectively, the data in the journal using XZ\&.
 160 .RE
 161 .PP
 162 \fB\-\-seal\fR, \fB\-\-no\-seal\fR
 163 .RS 4
 164 Periodically sign or not, respectively, the data in the journal using Forward Secure Sealing\&.
 165 .RE
 166 .PP
 167 \fB\-\-getter=\fR\fB\fIPROG \-\-option1 \-\-option2\fR\fR
 168 .RS 4
 169 Program to invoke to retrieve data\&. The journal event stream must be generated on standard output\&.
 170 .sp
 171 Examples:
 172 .sp
 173 .if n \{\
 174 .RS 4
 175 .\}
 176 .nf
 177 \-\-getter=\*(Aqcurl "\-HAccept: application/vnd\&.fdo\&.journal" https://some\&.host:19531/\*(Aq
 178 .fi
 179 .if n \{\
 180 .RE
 181 .\}
 182 .sp
 183 .if n \{\
 184 .RS 4
 185 .\}
 186 .nf
 187 \-\-getter=\*(Aqwget \-\-header="Accept: application/vnd\&.fdo\&.journal" \-O\- https://some\&.host:19531/\*(Aq
 188 .fi
 189 .if n \{\
 190 .RE
 191 .\}
 192 .RE
 193 .PP
 194 \fB\-h\fR, \fB\-\-help\fR
 195 .RS 4
 196 Print a short help text and exit\&.
 197 .RE
 198 .PP
 199 \fB\-\-version\fR
 200 .RS 4
 201 Print a short version string and exit\&.
 202 .RE
 203 .SH "EXAMPLES"
 204 .PP
 205 Copy local journal events to a different journal directory:
 206 .sp
 207 .if n \{\
 208 .RS 4
 209 .\}
 210 .nf
 211 journalctl \-o export | systemd\-journal\-remote \-o /tmp/dir \-
 212
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .PP
 218 Retrieve events from a remote
 219 \fBsystemd-journal-gatewayd\fR(8)
 220 instance and store them in
 221 /var/log/journal/some\&.host/remote\-some~host\&.journal:
 222 .sp
 223 .if n \{\
 224 .RS 4
 225 .\}
 226 .nf
 227 systemd\-journal\-remote \-\-url http://some\&.host:19531/
 228
 229 .fi
 230 .if n \{\
 231 .RE
 232 .\}
 233 .sp
 234 .SH "SEE ALSO"
 235 .PP
 236 \fBsystemd-journal-upload\fR(8),
 237 \fBjournalctl\fR(1),
 238 \fBsystemd-journald.service\fR(8),
 239 \fBsystemd-journal-gatewayd.service\fR(8)
 240 .SH "NOTES"
 241 .IP " 1." 4
 242 Journal Export Format
 243 .RS 4
 244 \%http://www.freedesktop.org/wiki/Software/systemd/export
 245 .RE
 246 .IP " 2." 4
 247 http://some.host:19531/
 248 .IP " 3." 4
 249 https://some.host:19531/