Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-JOURNAL\-GATEWAYD\&.SERVICE" "8" "" "systemd 261~rc3" "systemd-journal-gatewayd.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-gatewayd.service, systemd-journal-gatewayd.socket, systemd-journal-gatewayd \- HTTP server for journal events
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-journal\-gatewayd\&.service
27 .PP
28 systemd\-journal\-gatewayd\&.socket
29 .HP \w'\fB/usr/lib/systemd/systemd\-journal\-gatewayd\fR\ 'u
30 \fB/usr/lib/systemd/systemd\-journal\-gatewayd\fR [OPTIONS...]
31 .SH "DESCRIPTION"
32 .PP
33 \fBsystemd\-journal\-gatewayd\fR
34 serves journal events over the network\&. Clients must connect using HTTP\&. The server listens on port 19531 by default\&. If
35 \fB\-\-cert=\fR
36 is specified, the server expects HTTPS connections\&.
37 .PP
38 The program is started by
39 \fBsystemd\fR(1)
40 and expects to receive a single socket\&. Use
41 \fBsystemctl start systemd\-journal\-gatewayd\&.socket\fR
42 to start the service, and
43 \fBsystemctl enable systemd\-journal\-gatewayd\&.socket\fR
44 to have it started on boot\&.
45 .SH "OPTIONS"
46 .PP
47 The following options are understood:
48 .PP
49 \fB\-\-cert=\fR
50 .RS 4
51 Specify the path to a file or
52 \fBAF_UNIX\fR
53 stream socket to read the server certificate from\&. The certificate must be in PEM format\&. This option switches
54 \fBsystemd\-journal\-gatewayd\fR
55 into HTTPS mode and must be used together with
56 \fB\-\-key=\fR\&.
57 .sp
58 Added in version 198\&.
59 .RE
60 .PP
61 \fB\-\-key=\fR
62 .RS 4
63 Specify the path to a file or
64 \fBAF_UNIX\fR
65 stream socket to read the secret server key corresponding to the certificate specified with
66 \fB\-\-cert=\fR
67 from\&. The key must be in PEM format\&.
68 .sp
69 Added in version 198\&.
70 .RE
71 .PP
72 \fB\-\-trust=\fR
73 .RS 4
74 Specify the path to a file or
75 \fBAF_UNIX\fR
76 stream socket to read a CA certificate from\&. The certificate must be in PEM format\&.
77 .sp
78 Added in version 236\&.
79 .RE
80 .PP
81 \fB\-\-system\fR, \fB\-\-user\fR
82 .RS 4
83 Limit served entries to entries from system services and the kernel, or to entries from services of current user\&. This has the same meaning as
84 \fB\-\-system\fR
85 and
86 \fB\-\-user\fR
87 options for
88 \fBjournalctl\fR(1)\&. If neither is specified, all accessible entries are served\&.
89 .sp
90 Added in version 249\&.
91 .RE
92 .PP
93 \fB\-m\fR, \fB\-\-merge\fR
94 .RS 4
95 Serve entries interleaved from all available journals, including other machines\&. This has the same meaning as
96 \fB\-\-merge\fR
97 option for
98 \fBjournalctl\fR(1)\&.
99 .sp
100 Added in version 249\&.
101 .RE
102 .PP
103 \fB\-D \fR\fB\fIDIR\fR\fR, \fB\-\-directory=\fR\fB\fIDIR\fR\fR
104 .RS 4
105 Takes a directory path as argument\&. If specified,
106 \fBsystemd\-journal\-gatewayd\fR
107 will serve the specified journal directory
108 \fIDIR\fR
109 instead of the default runtime and system journal paths\&.
110 .sp
111 Added in version 232\&.
112 .RE
113 .PP
114 \fB\-\-file=\fR\fB\fIGLOB\fR\fR
115 .RS 4
116 Takes a file glob as an argument\&. Serve entries from the specified journal files matching
117 \fIGLOB\fR
118 instead of the default runtime and system journal paths\&. May be specified multiple times, in which case files will be suitably interleaved\&. This has the same meaning as
119 \fB\-\-file=\fR
120 option for
121 \fBjournalctl\fR(1)\&.
122 .sp
123 Added in version 249\&.
124 .RE
125 .PP
126 \fB\-h\fR, \fB\-\-help\fR
127 .RS 4
128 Print a short help text and exit\&.
129 .RE
130 .PP
131 \fB\-\-version\fR
132 .RS 4
133 Print a short version string and exit\&.
134 .RE
135 .SH "SUPPORTED URLS"
136 .PP
137 The following URLs are recognized:
138 .PP
139 /boots
140 .RS 4
141 Returns json\-seq (RFC 7464) response containing JSON objects, each one containing boot number, its ID and the timestamps of the first and last message\&. Boots are returned starting with the latest boot first and use the same schema as
142 \fBjournalctl \-\-list\-boots \-\-output json\fR\&.
143 .sp
144 Added in version 258\&.
145 .RE
146 .PP
147 /browse
148 .RS 4
149 Interactive browsing\&.
150 .sp
151 Added in version 197\&.
152 .RE
153 .PP
154 /entries[?option1&option2=value\&...]
155 .RS 4
156 Retrieval of events in various formats\&.
157 .sp
158 The
159 \fBAccept:\fR
160 part of the HTTP header determines the format\&. Supported values are described below\&.
161 .sp
162 The
163 \fBRange:\fR
164 part of the HTTP header determines the range of events returned\&. Supported values are described below\&.
165 .sp
166 GET parameters can be used to modify what events are returned\&. Supported parameters are described below\&.
167 .sp
168 Added in version 197\&.
169 .RE
170 .PP
171 /machine
172 .RS 4
173 Return a JSON structure describing the machine\&.
174 .sp
175 Example:
176 .sp
177 .if n \{\
178 .RS 4
179 .\}
180 .nf
181 { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
182 "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
183 "hostname" : "fedora",
184 "os_pretty_name" : "Fedora 19 (Rawhide)",
185 "virtualization" : "kvm",
186 \&...}
187 .fi
188 .if n \{\
189 .RE
190 .\}
191 .sp
192 Added in version 197\&.
193 .RE
194 .PP
195 /fields/\fIFIELD_NAME\fR
196 .RS 4
197 Return a list of values of this field present in the logs\&.
198 .sp
199 Added in version 197\&.
200 .RE
201 .SH "ACCEPT HEADER"
202 .PP
203 \fBAccept: \fR\fB\fIformat\fR\fR
204 .PP
205 Recognized formats:
206 .PP
207 \fBtext/plain\fR
208 .RS 4
209 The default\&. Plaintext syslog\-like output, one line per journal entry (like
210 \fBjournalctl \-\-output short\fR)\&.
211 .sp
212 Added in version 197\&.
213 .RE
214 .PP
215 \fBapplication/json\fR
216 .RS 4
217 Entries are formatted as JSON data structures, one per line (like
218 \fBjournalctl \-\-output json\fR)\&. See
219 \m[blue]\fBJournal JSON Format\fR\m[]\&\s-2\u[1]\d\s+2
220 for more information\&.
221 .sp
222 Added in version 197\&.
223 .RE
224 .PP
225 \fBtext/event\-stream\fR
226 .RS 4
227 Entries are formatted as JSON data structures, wrapped in a format suitable for
228 \m[blue]\fBServer\-Sent Events\fR\m[]\&\s-2\u[2]\d\s+2
229 (like
230 \fBjournalctl \-\-output json\-sse\fR)\&.
231 .sp
232 Added in version 229\&.
233 .RE
234 .PP
235 \fBapplication/vnd\&.fdo\&.journal\fR
236 .RS 4
237 Entries are serialized into a binary (but mostly text\-based) stream suitable for backups and network transfer (like
238 \fBjournalctl \-\-output export\fR)\&. See
239 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2
240 for more information\&.
241 .sp
242 Added in version 197\&.
243 .RE
244 .SH "RANGE HEADER"
245 .PP
246 \fBRange: entries=[\fR\fB\fIcursor\fR\fR\fB][[:\fR\fB\fInum_skip\fR\fR\fB]:[\fR\fB\fInum_entries\fR\fR\fB]]\fR
247 .PP
248 \fBRange: realtime=[\fR\fB\fIsince\fR\fR\fB]:[\fR\fB\fIuntil\fR\fR\fB][[:\fR\fB\fInum_skip\fR\fR\fB]:\fR\fB\fInum_entries\fR\fR\fB]\fR
249 .PP
250 where
251 \fIcursor\fR
252 is a cursor string, defaults to the first entry,
253 \fIsince\fR
254 and
255 \fIuntil\fR
256 are timestamps (seconds since 1970\-01\-01 00:00:00 UTC),
257 \fInum_skip\fR
258 is an integer,
259 \fInum_entries\fR
260 is an unsigned integer\&.
261 .PP
262 Range defaults to all available events\&.
263 .PP
264 If
265 \fInum_skip\fR
266 is negative and no
267 \fIcursor\fR
268 is given, the last entry will be the reference point\&.
269 .SH "URL GET PARAMETERS"
270 .PP
271 Following parameters can be used as part of the URL:
272 .PP
273 follow
274 .RS 4
275 wait for new events (like
276 \fBjournalctl \-\-follow\fR, the number of events returned is not limited, unless
277 \fInum_entries\fR
278 is specified in the
279 \fIRange\fR
280 header)\&.
281 .sp
282 Added in version 197\&.
283 .RE
284 .PP
285 discrete
286 .RS 4
287 Test that the specified cursor refers to an entry in the journal\&. Returns just this entry\&.
288 .sp
289 Added in version 197\&.
290 .RE
291 .PP
292 boot
293 .RS 4
294 Limit events to the current boot of the system (like
295 \fBjournalctl \-b\fR)\&.
296 .sp
297 Added in version 197\&.
298 .RE
299 .PP
300 \fIKEY\fR=\fImatch\fR
301 .RS 4
302 Match journal fields\&. See
303 \fBsystemd.journal-fields\fR(7)\&.
304 .sp
305 Added in version 197\&.
306 .RE
307 .SH "EXAMPLES"
308 .PP
309 Retrieve events from this boot from local journal in
310 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2:
311 .sp
312 .if n \{\
313 .RS 4
314 .\}
315 .nf
316 curl \-\-silent \-H\*(AqAccept: application/vnd\&.fdo\&.journal\*(Aq \e
317 \*(Aqhttp://localhost:19531/entries?boot\*(Aq
318 .fi
319 .if n \{\
320 .RE
321 .\}
322 .PP
323 Listen for core dumps:
324 .sp
325 .if n \{\
326 .RS 4
327 .\}
328 .nf
329 curl \*(Aqhttp://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1\*(Aq
330 .fi
331 .if n \{\
332 .RE
333 .\}
334 .SH "SEE ALSO"
335 .PP
336 \fBsystemd\fR(1), \fBjournalctl\fR(1), \fBsystemd.journal-fields\fR(7), \fBsystemd-journald.service\fR(8), \fBsystemd-journal-remote.service\fR(8), \fBsystemd-journal-upload.service\fR(8)
337 .SH "NOTES"
338 .IP " 1." 4
339 Journal JSON Format
340 .RS 4
341 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format
342 .RE
343 .IP " 2." 4
344 Server-Sent Events
345 .RS 4
346 \%https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events
347 .RE
348 .IP " 3." 4
349 Journal Export Format
350 .RS 4
351 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
352 .RE