Imported Upstream version 214

[systemd.git] / man / systemd-journal-gatewayd.service.8

'\" t
.TH "SYSTEMD\-JOURNAL\-GATEWAYD\&.SERVICE" "8" "" "systemd 214" "systemd-journal-gatewayd.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-gatewayd.service, systemd-journal-gatewayd.socket, systemd-journal-gatewayd \- HTTP server for journal events
.SH "SYNOPSIS"
.PP
systemd\-journal\-gatewayd\&.service
.PP
systemd\-journal\-gatewayd\&.socket
.HP \w'\fB/usr/lib/systemd/systemd\-journal\-gatewayd\fR\ 'u
\fB/usr/lib/systemd/systemd\-journal\-gatewayd\fR [OPTIONS...]
.SH "DESCRIPTION"
.PP
\fBsystemd\-journal\-gatewayd\fR
serves journal events over the network\&. Clients must connect using HTTP\&. The server listens on port 19531 by default\&. If
\fB\-\-cert=\fR
is specified, the server expects HTTPS connections\&.
.PP
The program is started by
\fBsystemd\fR(1)
and expects to receive a single socket\&. Use
\fBsystemctl start systemd\-journal\-gatewayd\&.socket\fR
to start the service, and
\fBsystemctl enable systemd\-journal\-gatewayd\&.socket\fR
to have it started on boot\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-cert=\fR
.RS 4
Specify the path to a file containing a server certificate in PEM format\&. This option switches
\fBsystemd\-journal\-gatewayd\fR
into HTTPS mode and must be used together with
\fB\-\-key=\fR\&.
.RE
.PP
\fB\-\-key=\fR
.RS 4
Specify the path to a file containing a server key in PEM format corresponding to the certificate specified with
\fB\-\-cert=\fR\&.
.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 "SUPPORTED URLS"
.PP
The following URLs are recognized:
.PP
/browse
.RS 4
Interactive browsing\&.
.RE
.PP
/entries[?option1&option2=value\&.\&.\&.]
.RS 4
Retrieval of events in various formats\&.
.sp
The
\fBAccept:\fR
part of the HTTP header determines the format\&. Supported values are described below\&.
.sp
The
\fBRange:\fR
part of the HTTP header determines the range of events returned\&. Supported values are described below\&.
.sp
GET parameters can be used to modify what events are returned\&. Supported parameters are described below\&.
.RE
.PP
/machine
.RS 4
Return a JSON structure describing the machine\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
  "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
  "hostname" : "fedora",
  "os_pretty_name" : "Fedora 19 (Rawhide)",
  "virtualization" : "kvm",
  \&.\&.\&.}
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
/fields/\fIFIELD_NAME\fR
.RS 4
Return a list of values of this field present in the logs\&.
.RE
.SH "ACCEPT HEADER"
.PP
\fBAccept: \fR\fB\fIformat\fR\fR
.PP
Recognized formats:
.PP
\fBtext/plain\fR
.RS 4
The default\&. Plaintext syslog\-like output, one line per journal entry (like
\fBjournalctl \-\-output short\fR)\&.
.RE
.PP
\fBapplication/json\fR
.RS 4
Entries are formatted as JSON data structures, one per line (like
\fBjournalctl \-\-output json\fR)\&. See
\m[blue]\fBJournal JSON Format\fR\m[]\&\s-2\u[1]\d\s+2
for more information\&.
.RE
.PP
\fBapplication/event\-stream\fR
.RS 4
Entries are formatted as JSON data structures, wrapped in a format suitable for
\m[blue]\fBServer\-Sent Events\fR\m[]\&\s-2\u[2]\d\s+2
(like
\fBjournalctl \-\-output json\-sse\fR)\&.
.RE
.PP
\fBapplication/vnd\&.fdo\&.journal\fR
.RS 4
Entries are serialized into a binary (but mostly text\-based) stream suitable for backups and network transfer (like
\fBjournalctl \-\-output export\fR)\&. See
\m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2
for more information\&.
.RE
.SH "RANGE HEADER"
.PP
\fBRange: entries=\fR\fB\fIcursor\fR\fR\fB[[:\fR\fB\fInum_skip\fR\fR\fB]:\fR\fB\fInum_entries\fR\fR\fB]\fR
.PP
where
\fBcursor\fR
is a cursor string,
\fBnum_skip\fR
is an integer,
\fBnum_entries\fR
is an unsigned integer\&.
.PP
Range defaults to all available events\&.
.SH "URL GET PARAMETERS"
.PP
Following parameters can be used as part of the URL:
.PP
follow
.RS 4
wait for new events (like
\fBjournalctl \-\-follow\fR, except that the number of events returned is not limited)\&.
.RE
.PP
discrete
.RS 4
Test that the specified cursor refers to an entry in the journal\&. Returns just this entry\&.
.RE
.PP
boot
.RS 4
Limit events to the current boot of the system (like
\fBjournalctl \-\-this\-\-boot\fR)\&.
.RE
.PP
\fIKEY\fR=\fImatch\fR
.RS 4
Match journal fields\&. See
\fBsystemd.journal-fields\fR(7)\&.
.RE
.SH "EXAMPLES"
.PP
Retrieve events from this boot from local journal in
\m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[3]\d\s+2:
.sp
.if n \{\
.RS 4
.\}
.nf
curl \-\-silent \-H\*(AqAccept: application/vnd\&.fdo\&.journal\*(Aq \e
       \*(Aqhttp://localhost:19531/entries?boot\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
Listen for core dumps:
.sp
.if n \{\
.RS 4
.\}
.nf
curl \*(Aqhttp://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1\*(Aq
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBjournalctl\fR(1),
\fBsystemd-journald.service\fR(8),
\fBsystemd.journal-fields\fR(7),
.SH "NOTES"
.IP " 1." 4
Journal JSON Format
.RS 4
\%http://www.freedesktop.org/wiki/Software/systemd/json
.RE
.IP " 2." 4
Server-Sent Events
.RS 4
\%https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events
.RE
.IP " 3." 4
Journal Export Format
.RS 4
\%http://www.freedesktop.org/wiki/Software/systemd/export
.RE