Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-JOURNAL\-GATEWAYD\&.SERVICE" "8" "" "systemd 257.13" "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 /browse
140 .RS 4
141 Interactive browsing\&.
142 .sp
143 Added in version 197\&.
144 .RE
145 .PP
146 /entries[?option1&option2=value\&...]
147 .RS 4
148 Retrieval of events in various formats\&.
149 .sp
150 The
151 \fBAccept:\fR
152 part of the HTTP header determines the format\&. Supported values are described below\&.
153 .sp
154 The
155 \fBRange:\fR
156 part of the HTTP header determines the range of events returned\&. Supported values are described below\&.
157 .sp
158 GET parameters can be used to modify what events are returned\&. Supported parameters are described below\&.
159 .sp
160 Added in version 197\&.
161 .RE
162 .PP
163 /machine
164 .RS 4
165 Return a JSON structure describing the machine\&.
166 .sp
167 Example:
168 .sp
169 .if n \{\
170 .RS 4
171 .\}
172 .nf
173 { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
174 "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
175 "hostname" : "fedora",
176 "os_pretty_name" : "Fedora 19 (Rawhide)",
177 "virtualization" : "kvm",
178 \&...}
179 .fi
180 .if n \{\
181 .RE
182 .\}
183 .sp
184 Added in version 197\&.
185 .RE
186 .PP
187 /fields/\fIFIELD_NAME\fR
188 .RS 4
189 Return a list of values of this field present in the logs\&.
190 .sp
191 Added in version 197\&.
192 .RE
193 .SH "ACCEPT HEADER"
194 .PP
195 \fBAccept: \fR\fB\fIformat\fR\fR
196 .PP
197 Recognized formats:
198 .PP
199 \fBtext/plain\fR
200 .RS 4
201 The default\&. Plaintext syslog\-like output, one line per journal entry (like
202 \fBjournalctl \-\-output short\fR)\&.
203 .sp
204 Added in version 197\&.
205 .RE
206 .PP
207 \fBapplication/json\fR
208 .RS 4
209 Entries are formatted as JSON data structures, one per line (like
210 \fBjournalctl \-\-output json\fR)\&. See
211 \m[blue]\fBJournal JSON Format\fR\m[]\&\s-2\u[1]\d\s+2
212 for more information\&.
213 .sp
214 Added in version 197\&.
215 .RE
216 .PP
217 \fBtext/event\-stream\fR
218 .RS 4
219 Entries are formatted as JSON data structures, wrapped in a format suitable for
220 \m[blue]\fBServer\-Sent Events\fR\m[]\&\s-2\u[2]\d\s+2
221 (like
222 \fBjournalctl \-\-output json\-sse\fR)\&.
223 .sp
224 Added in version 229\&.
225 .RE
226 .PP
227 \fBapplication/vnd\&.fdo\&.journal\fR
228 .RS 4
229 Entries are serialized into a binary (but mostly text\-based) stream suitable for backups and network transfer (like
230 \fBjournalctl \-\-output export\fR)\&. See
231 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2
232 for more information\&.
233 .sp
234 Added in version 197\&.
235 .RE
236 .SH "RANGE HEADER"
237 .PP
238 \fBRange: entries=\fR\fB\fIcursor\fR\fR\fB[[:\fR\fB\fInum_skip\fR\fR\fB]:\fR\fB\fInum_entries\fR\fR\fB]\fR
239 .PP
240 \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
241 .PP
242 where
243 \fIcursor\fR
244 is a cursor string,
245 \fIsince\fR
246 and
247 \fIuntil\fR
248 are timestamps (seconds since 1970\-01\-01 00:00:00 UTC),
249 \fInum_skip\fR
250 is an integer,
251 \fInum_entries\fR
252 is an unsigned integer\&.
253 .PP
254 Range defaults to all available events\&.
255 .SH "URL GET PARAMETERS"
256 .PP
257 Following parameters can be used as part of the URL:
258 .PP
259 follow
260 .RS 4
261 wait for new events (like
262 \fBjournalctl \-\-follow\fR, except that the number of events returned is not limited)\&.
263 .sp
264 Added in version 197\&.
265 .RE
266 .PP
267 discrete
268 .RS 4
269 Test that the specified cursor refers to an entry in the journal\&. Returns just this entry\&.
270 .sp
271 Added in version 197\&.
272 .RE
273 .PP
274 boot
275 .RS 4
276 Limit events to the current boot of the system (like
277 \fBjournalctl \-b\fR)\&.
278 .sp
279 Added in version 197\&.
280 .RE
281 .PP
282 \fIKEY\fR=\fImatch\fR
283 .RS 4
284 Match journal fields\&. See
285 \fBsystemd.journal-fields\fR(7)\&.
286 .sp
287 Added in version 197\&.
288 .RE
289 .SH "EXAMPLES"
290 .PP
291 Retrieve events from this boot from local journal in
292 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2:
293 .sp
294 .if n \{\
295 .RS 4
296 .\}
297 .nf
298 curl \-\-silent \-H\*(AqAccept: application/vnd\&.fdo\&.journal\*(Aq \e
299 \*(Aqhttp://localhost:19531/entries?boot\*(Aq
300 .fi
301 .if n \{\
302 .RE
303 .\}
304 .PP
305 Listen for core dumps:
306 .sp
307 .if n \{\
308 .RS 4
309 .\}
310 .nf
311 curl \*(Aqhttp://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1\*(Aq
312 .fi
313 .if n \{\
314 .RE
315 .\}
316 .SH "SEE ALSO"
317 .PP
318 \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)
319 .SH "NOTES"
320 .IP " 1." 4
321 Journal JSON Format
322 .RS 4
323 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format
324 .RE
325 .IP " 2." 4
326 Server-Sent Events
327 .RS 4
328 \%https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events
329 .RE
330 .IP " 3." 4
331 Journal Export Format
332 .RS 4
333 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
334 .RE