Debian Codegraph @

upstream/debian-unstable/man8/systemd-journal-remote.service.8

raw
1 '\" t
2 .TH "SYSTEMD\-JOURNAL\-REMOTE\&.SERVICE" "8" "" "systemd 261~rc3" "systemd-journal-remote.service"
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.service, systemd-journal-remote.socket, systemd-journal-remote \- Receive journal messages over the network
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-journal\-remote\&.service
27 .PP
28 systemd\-journal\-remote\&.socket
29 .HP \w'\fB/usr/lib/systemd/systemd\-journal\-remote\fR\ 'u
30 \fB/usr/lib/systemd/systemd\-journal\-remote\fR [OPTIONS...] [\-o/\-\-output=\fIDIR\fR|\fIFILE\fR] [SOURCES...]
31 .SH "DESCRIPTION"
32 .PP
33 \fBsystemd\-journal\-remote\fR
34 is a command to receive serialized journal events and store them to journal files\&. Input streams are in the
35 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[1]\d\s+2, i\&.e\&. like the output from
36 \fBjournalctl \-\-output=export\fR\&. For transport over the network, this serialized stream is usually carried over an HTTPS connection\&.
37 .PP
38 systemd\-journal\-remote\&.service
39 is a system service that uses
40 \fBsystemd\-journal\-remote\fR
41 to listen for connections\&.
42 systemd\-journal\-remote\&.socket
43 configures the network address that
44 systemd\-journal\-remote\&.service
45 listens on\&. By default, this is port 19532\&. What connections are accepted and how the received data is stored can be configured through the
46 \fBjournal-remote.conf\fR(5)
47 configuration file\&.
48 .SH "SOURCES"
49 .PP
50 Sources can be either "active" (\fBsystemd\-journal\-remote\fR
51 requests and pulls the data), or "passive" (\fBsystemd\-journal\-remote\fR
52 waits for a connection and then receives events pushed by the other side)\&.
53 .PP
54 \fBsystemd\-journal\-remote\fR
55 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)\&.
56 .PP
57 When there are no more connections, and no more can be created (there are no listening sockets), then
58 \fBsystemd\-journal\-remote\fR
59 will exit\&.
60 .PP
61 Active sources can be specified in the following ways:
62 .PP
63 [SOURCES]
64 .RS 4
65 When
66 \fB\-\fR
67 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\&.
68 .sp
69 Added in version 239\&.
70 .RE
71 .PP
72 \fB\-\-url=\fR\fB\fIADDRESS\fR\fR
73 .RS 4
74 With the
75 \fB\-\-url=\fR\fB\fIADDRESS\fR\fR
76 option, events will be retrieved using HTTP from
77 \fIADDRESS\fR\&. This URL should refer to the root of a remote
78 \fBsystemd-journal-gatewayd\fR(8)
79 instance, e\&.g\&. http://some\&.host:19531/ or https://some\&.host:19531/\&.
80 .sp
81 Added in version 239\&.
82 .RE
83 .PP
84 \fB\-\-getter=\*(Aq\fR\fB\fIPROG\fR\fR\fB \fR\fB[OPTIONS]\fR\fB\*(Aq\fR
85 .RS 4
86 Program to invoke to retrieve data\&. The journal event stream must be generated on standard output\&.
87 .sp
88 Examples:
89 .sp
90 .if n \{\
91 .RS 4
92 .\}
93 .nf
94 \-\-getter=\*(Aqcurl "\-HAccept: application/vnd\&.fdo\&.journal" https://some\&.host:19531/\*(Aq
95 .fi
96 .if n \{\
97 .RE
98 .\}
99 .sp
100 .if n \{\
101 .RS 4
102 .\}
103 .nf
104 \-\-getter=\*(Aqwget \-\-header="Accept: application/vnd\&.fdo\&.journal" \-O\- https://some\&.host:19531/\*(Aq
105 .fi
106 .if n \{\
107 .RE
108 .\}
109 .sp
110 Added in version 239\&.
111 .RE
112 .PP
113 Passive sources can be specified in the following ways:
114 .PP
115 \fB\-\-listen\-raw=\fR\fB\fIADDRESS\fR\fR
116 .RS 4
117 \fIADDRESS\fR
118 must be an address suitable for
119 \fBListenStream=\fR
120 (cf\&.
121 \fBsystemd.socket\fR(5))\&.
122 \fBsystemd\-journal\-remote\fR
123 will listen on this socket for connections\&. Each connection is expected to be a stream of journal events\&.
124 .sp
125 Added in version 239\&.
126 .RE
127 .PP
128 \fB\-\-listen\-http=\fR\fB\fIADDRESS\fR\fR, \fB\-\-listen\-https=\fR\fB\fIADDRESS\fR\fR
129 .RS 4
130 \fIADDRESS\fR
131 must be either a negative integer, in which case it will be interpreted as the (negated) file descriptor number, or an address suitable for
132 \fBListenStream=\fR
133 (c\&.f\&.
134 \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
135 \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
136 \fB\-\-listen\-http=\fR
137 and
138 \fB\-\-listen\-https=\fR\&. Currently, only POST requests to
139 /upload
140 with
141 "Content\-Type: application/vnd\&.fdo\&.journal"
142 are supported\&.
143 .sp
144 Added in version 239\&.
145 .RE
146 .PP
147 \fI$LISTEN_FDS\fR
148 .RS 4
149 \fBsystemd\-journal\-remote\fR
150 supports the
151 \fI$LISTEN_FDS\fR/\fI$LISTEN_PID\fR
152 protocol\&. Open sockets inherited through socket activation behave like those opened with
153 \fB\-\-listen\-raw=\fR
154 described above, unless they are specified as an argument in
155 \fB\-\-listen\-http=\-\fR\fB\fIn\fR\fR
156 or
157 \fB\-\-listen\-https=\-\fR\fB\fIn\fR\fR
158 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\&.
159 .sp
160 Added in version 239\&.
161 .RE
162 .PP
163 \fB\-\-key=\fR
164 .RS 4
165 Takes a path to a SSL secret key file in PEM format\&. Defaults to
166 /etc/ssl/private/journal\-remote\&.pem\&. This option can be used with
167 \fB\-\-listen\-https=\fR\&. If the path refers to an
168 \fBAF_UNIX\fR
169 stream socket in the file system a connection is made to it and the key read from it\&.
170 .sp
171 Added in version 239\&.
172 .RE
173 .PP
174 \fB\-\-cert=\fR
175 .RS 4
176 Takes a path to a SSL certificate file in PEM format\&. Defaults to
177 /etc/ssl/certs/journal\-remote\&.pem\&. This option can be used with
178 \fB\-\-listen\-https=\fR\&. If the path refers to an
179 \fBAF_UNIX\fR
180 stream socket in the file system a connection is made to it and the certificate read from it\&.
181 .sp
182 Added in version 239\&.
183 .RE
184 .PP
185 \fB\-\-trust=\fR
186 .RS 4
187 Takes a path to a SSL CA certificate file in PEM format, or
188 \fBall\fR\&. If
189 \fBall\fR
190 is set, then certificate checking will be disabled\&. Defaults to
191 /etc/ssl/ca/trusted\&.pem\&. This option can be used with
192 \fB\-\-listen\-https=\fR\&. If the path refers to an
193 \fBAF_UNIX\fR
194 stream socket in the file system a connection is made to it and the certificate read from it\&.
195 .sp
196 Added in version 239\&.
197 .RE
198 .PP
199 \fB\-\-gnutls\-log=\fR
200 .RS 4
201 Takes a comma separated list of gnutls logging categories\&. This option can be used with
202 \fB\-\-listen\-http=\fR
203 or
204 \fB\-\-listen\-https=\fR\&.
205 .sp
206 Added in version 239\&.
207 .RE
208 .SH "SINKS"
209 .PP
210 The location of the output journal can be specified with
211 \fB\-o\fR
212 or
213 \fB\-\-output=\fR\&.
214 .PP
215 \fB\-o \fR\fB\fIFILE\fR\fR, \fB\-\-output=\fR\fB\fIFILE\fR\fR
216 .RS 4
217 Will write to this journal file\&. The filename must end with
218 \&.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\&.
219 .sp
220 Added in version 239\&.
221 .RE
222 .PP
223 \fB\-o \fR\fB\fIDIR\fR\fR, \fB\-\-output=\fR\fB\fIDIR\fR\fR
224 .RS 4
225 Will create journal files underneath directory
226 \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
227 \fIDIR\fR
228 will be generated using the rules described below\&.
229 .sp
230 Added in version 239\&.
231 .RE
232 .PP
233 If
234 \fB\-\-output=\fR
235 is not used, the output directory
236 /var/log/journal/remote/
237 will be used\&. In case the output file is not specified, journal files will be created underneath the selected directory\&. Files will be called
238 remote\-\fIhostname\fR\&.journal, where the
239 \fIhostname\fR
240 part is the escaped hostname of the source endpoint of the connection, or the numerical address if the hostname cannot be determined\&.
241 .PP
242 In the case that "active" sources are given by the positional arguments or
243 \fB\-\-getter=\fR
244 option, the output file name must always be given explicitly\&.
245 .SH "OPTIONS"
246 .PP
247 The following options are understood:
248 .PP
249 \fB\-\-split\-mode\fR
250 .RS 4
251 One of
252 \fBnone\fR
253 or
254 \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\&.
255 .sp
256 In the case that "active" sources are given by the positional arguments or
257 \fB\-\-getter=\fR
258 option, the output file name must always be given explicitly and only
259 \fBnone\fR
260 is allowed\&.
261 .sp
262 Added in version 239\&.
263 .RE
264 .PP
265 \fB\-\-compress\fR [\fIBOOL\fR]
266 .RS 4
267 If this is set to
268 "yes"
269 then compress the data in the journal using XZ\&. The default is
270 "yes"\&.
271 .sp
272 Added in version 239\&.
273 .RE
274 .PP
275 \fB\-\-seal\fR [\fIBOOL\fR]
276 .RS 4
277 If this is set to
278 "yes"
279 then periodically sign the data in the journal using Forward Secure Sealing\&. The default is
280 "no"\&.
281 .sp
282 Added in version 239\&.
283 .RE
284 .PP
285 \fB\-\-max\-use=\fR, \fB\-\-keep\-free=\fR, \fB\-\-max\-file\-size=\fR, \fB\-\-max\-files=\fR
286 .RS 4
287 These options override the corresponding settings from the configuration file (see
288 \fBjournal-remote.conf\fR(5))\&. See that page for the descriptions of these options\&.
289 .sp
290 Added in version 261\&.
291 .RE
292 .PP
293 \fB\-h\fR, \fB\-\-help\fR
294 .RS 4
295 Print a short help text and exit\&.
296 .RE
297 .PP
298 \fB\-\-version\fR
299 .RS 4
300 Print a short version string and exit\&.
301 .RE
302 .SH "EXAMPLES"
303 .PP
304 Copy local journal events to a different journal directory:
305 .sp
306 .if n \{\
307 .RS 4
308 .\}
309 .nf
310 journalctl \-o export | systemd\-journal\-remote \-o /tmp/dir/foo\&.journal \-
311 .fi
312 .if n \{\
313 .RE
314 .\}
315 .PP
316 Retrieve all available events from a remote
317 \fBsystemd-journal-gatewayd\fR(8)
318 instance and store them in
319 /var/log/journal/remote/remote\-some\&.host\&.journal:
320 .sp
321 .if n \{\
322 .RS 4
323 .\}
324 .nf
325 systemd\-journal\-remote \-\-url http://some\&.host:19531/
326 .fi
327 .if n \{\
328 .RE
329 .\}
330 .PP
331 Retrieve current boot events and wait for new events from a remote
332 \fBsystemd-journal-gatewayd\fR(8)
333 instance, and store them in
334 /var/log/journal/remote/remote\-some\&.host\&.journal:
335 .sp
336 .if n \{\
337 .RS 4
338 .\}
339 .nf
340 systemd\-journal\-remote \-\-url http://some\&.host:19531/entries?boot&follow
341 .fi
342 .if n \{\
343 .RE
344 .\}
345 .sp
346 .SH "SEE ALSO"
347 .PP
348 \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)
349 .SH "NOTES"
350 .IP " 1." 4
351 Journal Export Format
352 .RS 4
353 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
354 .RE