1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2012 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'>
27 <title>systemd-journal-remote</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Zbigniew</firstname>
34 <surname>Jędrzejewski-Szmek</surname>
35 <email>zbyszek@in.waw.pl</email>
41 <refentrytitle>systemd-journal-remote</refentrytitle>
42 <manvolnum>8</manvolnum>
46 <refname>systemd-journal-remote</refname>
47 <refpurpose>Stream journal messages over the network</refpurpose>
52 <command>systemd-journal-remote</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="opt" rep="norepeat">-o/--output=DIR|FILE</arg>
55 <arg choice="opt" rep="repeat">SOURCES</arg>
60 <title>Description</title>
63 <filename>systemd-journal-remote</filename> is a command to
64 receive serialized journal events and store them to the journal.
65 Input streams must be in the
66 <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export">
69 i.e. like the output from
70 <command>journalctl --output=export</command>.
75 <title>Sources</title>
78 Sources can be either "active"
79 (<command>systemd-journal-remote</command> requests and pulls
80 the data), or "passive"
81 (<command>systemd-journal-remote</command> waits for a
82 connection and then receives events pushed by the other side).
86 <command>systemd-journal-remote</command> can read more than one
87 event stream at a time. They will be interleaved in the output
88 file. In case of "active" connections, each "source" is one
89 stream, and in case of "passive" connections, each connection can
90 result in a separate stream. Sockets can be configured in
91 "accept" mode (i.e. only one connection), or "listen" mode (i.e.
92 multiple connections, each resulting in a stream).
96 When there are no more connections, and no more can be created
97 (there are no listening sockets), then
98 <command>systemd-journal-remote</command> will exit.
101 <para>Active sources can be specified in the following
106 <listitem><para>When <option>-</option> is given as a
107 positional argument, events will be read from standard input.
108 Other positional arguments will be treated as filenames
109 to open and read from.</para></listitem>
113 <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
115 <listitem><para>With the
116 <option>--url=<replaceable>ADDRESS</replaceable></option> option,
117 events will be retrieved using HTTP from
118 <replaceable>ADDRESS</replaceable>. This URL should refer to the
120 <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
121 instance (e.g. <ulink>http://some.host:19531/</ulink> or
122 <ulink>https://some.host:19531/</ulink>).</para></listitem>
126 <para>Passive sources can be specified in the following
131 <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
133 <listitem><para><replaceable>ADDRESS</replaceable> must be an
134 address suitable for <option>ListenStream=</option> (cf.
135 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
136 <command>systemd-journal-remote</command> will listen on this
137 socket for connections. Each connection is expected to be a
138 stream of journal events.</para>
143 <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
144 <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
146 <listitem><para><replaceable>ADDRESS</replaceable> must be
147 either a negative integer, in which case it will be
148 interpreted as the (negated) file descriptor number, or an
149 address suitable for <option>ListenStream=</option> (c.f.
150 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
151 In the first case, matching file descriptor must be inherited
153 <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
154 In the second case, an HTTP or HTTPS server will be spawned on
155 this port, respectively for <option>--listen-http</option> and
156 <option>--listen-https</option>. Currenntly, only POST requests
157 to <filename>/upload</filename> with <literal>Content-Type:
158 application/vnd.fdo.journal</literal> are supported.</para>
163 <term><varname>$LISTEN_FDS</varname></term>
165 <listitem><para><command>systemd-journal-remote</command>
167 <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
168 protocol. Open sockets inherited through socket activation
169 behave like those opened with <option>--listen-raw=</option>
170 described above, unless they are specified as an argument in
171 <option>--listen-http=-<replaceable>n</replaceable></option>
173 <option>--listen-https=-<replaceable>n</replaceable></option>
174 above. In the latter case, an HTTP or HTTPS server will be
175 spawned using this descriptor and connections must be made
176 over the HTTP protocol.</para>
186 <para>The location of the output journal can be specified
187 with <option>-o</option> or <option>--output=</option>.
192 <term><option>--output=<replaceable>FILE</replaceable></option></term>
194 <listitem><para>Will write to this journal. The filename must
195 end with <filename>.journal</filename>. The file will be
196 created if it does not exist. If necessary (journal file
197 full, or corrupted), the file will be renamed following normal
198 journald rules and a new journal file will be created in its
199 stead.</para></listitem>
203 <term><option>--output=<replaceable>DIR</replaceable></option></term>
205 <listitem><para>Will create journal files underneath directory
206 <replaceable>DIR</replaceable>. The directory must exist. If
207 necessary (journal files over size, or corrupted), journal
208 files will be rotated following normal journald rules. Names
209 of files underneath <replaceable>DIR</replaceable> will be
210 generated using the rules described below.</para></listitem>
214 <para>If <option>--output=</option> is not used, the output directory
215 <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
216 will be used, where <replaceable>machine-id</replaceable> is the
217 identifier of the current system (see
218 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
219 In case the output file is not specified, journal files will be
220 created underneath the selected directory. Files will be called
221 <filename>remote-<replaceable>variable</replaceable>.journal</filename>,
222 where the <replaceable>variable</replaceable> part is generated
223 based on what passive and active sources are specified. It is
224 recommended to give a full output filename.</para>
226 <para>In case of "active" sources, if the hostname is known, it
227 will be used in the <replaceable>variable</replaceable> part.
228 Otherwise, local address and port number will be used, or
229 <literal>stdin</literal> for events passed over standard
230 input, and <literal>multiple</literal> if more than one source
235 <title>Options</title>
237 <para>The following options are understood:</para>
241 <term><option>--help</option></term>
242 <term><option>-h</option></term>
244 <listitem><para>Print a short help
245 text and exit.</para></listitem>
249 <term><option>--version</option></term>
251 <listitem><para>Print a short version
252 string and exit.</para></listitem>
256 <term><option>--compress</option></term>
257 <term><option>--no-compress</option></term>
259 <listitem><para>Compress or not, respectively, the data in the
260 journal using XZ.</para></listitem>
264 <term><option>--seal</option></term>
265 <term><option>--no-seal</option></term>
267 <listitem><para>Periodically sign or not, respectively, the
268 data in the journal using Forward Secure Sealing.
273 <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
275 <listitem><para>Program to invoke to retrieve data. The journal
276 event stream must be generated on standard output.</para>
278 <para>Examples:</para>
280 <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
282 <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
289 <title>Examples</title>
290 <para>Copy local journal events to a different journal directory:
292 journalctl -o export | systemd-journal-remote -o /tmp/dir -
296 <para>Retrieve events from a remote
297 <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
298 instance and store them in
299 <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
301 systemd-journal-remote --url http://some.host:19531/
307 <title>See Also</title>
309 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
311 <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.