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">
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 than 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><option>ADDRESS</option> must be an address
134 suitable for <option>ListenStream=</option> (c.f.
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><varname>$LISTEN_FDS</varname></term>
145 <listitem><para><command>systemd-journal-remote</command>
147 <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
148 protocol. Open sockets inherited through socket
149 activation behave like those opened with
150 <option>--listen-raw=</option> described above.
161 <para>The location of the output journal can be specified
162 with <option>-o</option> or <option>--output=</option>.
167 <term><option>--output=<replaceable>FILE</replaceable></option></term>
169 <listitem><para>Will write to this journal. The filename must
170 end with <filename>.journal</filename>. The file will be
171 created if it does not exist. When necessary (journal file
172 full, or corrupted) the file will be renamed following normal
173 journald rules and a new journal file will be created in it's
174 stead. </para></listitem>
178 <term><option>--output=<replaceable>DIR</replaceable></option></term>
180 <listitem><para>Will create journal files underneath directory
181 <replaceable>DIR</replaceable>. The directory must exist. When
182 necessary (journal files over size, or corrupted) journal
183 files will be rotated following normal journald rules. Names
184 of files underneath <replaceable>DIR</replaceable> will be
185 generated using the rules described below.</para></listitem>
189 <para>If <option>--output=</option> is not used, output directory
190 <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
191 will be used, where <replaceable>machine-id</replaceable> is the
192 identifier of the current system (see
193 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
194 In case the output file is not specified, journal files will be
195 created underneath the selected directory. Files will be called
196 <filename>remote-<replaceable>variable</replaceable>.journal</filename>,
197 where the <replaceable>variable</replaceable> part is generated
198 based on what passive and active sources are specified. It is
199 recommended to give a full output filename.</para>
201 <para>In case of "active" sources, if the hostname is known it
202 will be used in the <replaceable>variable</replaceable> part.
203 Otherwise, local address and port number will be used, or
204 <literal>stdin</literal> for events passed over standard
205 input, and <literal>multiple</literal> if more than one source
210 <title>Options</title>
212 <para>The following options are understood:</para>
216 <term><option>--help</option></term>
217 <term><option>-h</option></term>
219 <listitem><para>Print a short help
220 text and exit.</para></listitem>
224 <term><option>--version</option></term>
226 <listitem><para>Print a short version
227 string and exit.</para></listitem>
231 <term><option>--compress</option></term>
232 <term><option>--no-compress</option></term>
234 <listitem><para>Compress or not, respectively, the data in the
235 journal using XZ.</para></listitem>
239 <term><option>--seal</option></term>
240 <term><option>--no-seal</option></term>
242 <listitem><para>Periodically sign or not, respectively, the
243 data in the journal using Forward Secure Sealing.
248 <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
250 <listitem><para>Program to invoke to retrieve data. Journal
251 event stream must be generated on standard output.</para>
253 <para>Examples:</para>
255 <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
257 <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
264 <title>Examples</title>
265 <para>Copy local journal events to a different journal directory:
267 journalctl -o export | systemd-journal-remote -o /tmp/dir -
271 <para>Retrieve events from a remote
272 <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
273 instance and store them in
274 <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
276 systemd-journal-remote --url http://some.host:19531/
282 <title>See Also</title>
284 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.