On Tue, Nov 20, 2012 at 03:35:30AM +0100, Zbigniew Jędrzejewski-Szmek wrote:
> I guess that writing a man-page is in order...
So, to make things concrete, I've put together a wish-list manpage,
which describe some things which are there and quite a few things
which are not there yet. If this is accepted, then I'll start to fix
the code to follow the docs.
I'm pushing this to git://in.waw.pl/git/systemd branch remote.
Zbyszek
---------------------------------------------------------------------------
SYSTEMD-JOURNAL-RE(8) systemd-journal-remote SYSTEMD-JOURNAL-RE(8)
NAME
systemd-journal-remote, systemd-journal-remote.service, systemd-
journal-remote.socket - Stream journal messages over the network
SYNOPSIS
systemd-journal-remote [OPTIONS...] [-o/--output=DIR|FILE] [SOURCES...]
systemd-journal-remote.service
systemd-journal-remote.socket
DESCRIPTION
systemd-journal-remote is a command to receive journal events and store
them to the journal. Input streams must be in the Journal Export
Format[1], i.e. like the output from journalctl --output=export.
SOURCES
Sources can be either "active" (systemd-journal-remote requests and
pulls the data), or "passive" (systemd-journal-remote waits for a
connection and than receives events pushed by the other side).
systemd-journal-remote can read more than one event stream at a time.
They will be interleaved in the output file. In case of "active"
connections, each "source" is one stream, and in case of "passive"
connections each connection can result in a separate stream. Sockets
can be configured in "accept" mode (i.e. only one connection), or
"listen" mode (i.e. multiple connections, each resulting in a stream).
When there are no more connections, and no more can be created (there
are no listening sockets), then systemd-journal-remote will exit.
Active sources can be specified in the following ways:
When - is given as an argument, events will be read from standard
input.
When an URL is given systemd-journal-remote will retrieve messages
over HTTP or HTTPS. The URL should refer to the root of a remote
systemd-journal-gatewayd(8) instance (e.g.
http://some.host:19531/).
If the URL starts with ssh:// an ssh(1) connection will be opened
and journalctl(1) will be launched on the remote host (e.g.
ssh://u...@some.host). Messages will be sent over the encrypted
connection and stored locally.
If a file path is given, journal events will be read from local
disk. If the path refers to an exisiting file, just this file will
be read. If the path refers to an exisiting directory, journal
files underneath this directory will be read (like with journalctl
--directory=).
Passive sources can be specified in the following ways:
--listen=ADDRESS
ADDRESS must be an address suitable for ListenStream= (c.f.
systemd.socket(5)). A stream of journal events in expected.
--listen-http=ADDRESS
ADDRESS must be an address suitable for ListenStream= (c.f.
systemd.socket(5)). An HTTP POST request is expected to /events.
--listen-https=ADDRESS
ADDRESS must be an address suitable for ListenStream= (c.f.
systemd.socket(5)). An HTTPS POST request is expected to /events.
$LISTEN_FDS
When systemd-journal-remote is started as a service
(systemd-journal-remote.service unit) sockets configured in
systemd-journal-remote.socket will be passed using $LISTEN_FDS.
By default, open sockets passed through socket activation behave
like those opened with --listen= described above. If
--listen-http=-<n> or --listen-https=-<n> is used, HTTP and HTTPS
connections will be expected like with the options --listen-http=
and --listen-https= above. Integer <n> refers to the n-th socket of
$LISTEN_FDS, and must be in the range 0 .. $LISTEN_FDS-1.
SINKS
The location of the output journal can be specified with -o or
--output=.
--output=FILE
Will write to this journal. The filename must end with .journal.
The file will be created if it does not exist. When necessary
(journal file full, or corrupted) the file will be renamed
following normal journald rules and a new journal file will be
created in it's stead.
--output=DIR
Will create journal files underneath directory DIR. The directory
must exist. When necessary (journal files full, or corrupted)
journal files will be renamed following normal journald rules.
Names of files underneath DIR will be generated using the rules
described below.
If --output= is not used, directory /var/log/journal/<hostname>/ will
be used, if the hostname is known and trusted (see --trust-hostname=
below), or /var/log/journal/remote/ otherwise.
In case the output file is not specified, journal files will be created
underneath the selected directory. Files will be called
remote-<variable>.journal, where the <variable> part depends on the
connection. In case of "active" sources, if the hostname is known it
will be used the variable path. In case of "passive" sources, the
hostname will be used if it is known and trusted (see --trust-hostname
below). Otherwise, local address and port number will be used, or
'stdin' for events passwd over standard input.
standard input (-) and local paths will be mapped to
remote-stream.journal
http://<hostname>/, https://..., and ssh://... will be mapped to
remote-<hostname>.journal
OPTIONS
The following options are understood:
--help, -h
Print a short help text and exit.
--version
Print a short version string and exit.
--compress, --no-compress
Compress or not, respectively, the data in the journal using XZ.
--getter='PROG --option1 --option2'
Program to invoke on an URL to retrieve data. Journal event stream
must be generated on standard output.
Examples:
--getter='curl "-HAccept: application/vnd.fdo.journal"'
--getter='wget --header="Accept: application/vnd.fdo.journal"
-O-'
--trust-hostname=no, --trust-hostname=cert, --trust-hostname=always
Control the level of trust given to the hostname retrieved from DNS
for the connecting host. no, the default, means that the hostname
will not be used to determine the name of the output file. cert
means that the hostname will be used in case of hosts authenticated
through a trusted certificate. always means to trust
unconditionally.
EXAMPLES
Copy local journal events to a different journal directory:
journalctl -o export | systemd-journal-remote -o /tmp/dir -
Retrieve events from a remote systemd-journal-gatewayd(8) instance and
store them in /var/log/journal/some.host/remote-some~host.journal:
systemd-journal-remote http://some.host:19531/
Retrieve events from a remote systemd-journal-gatewayd(8) instance over
SSH and store them in /tmp/dir/some~host.journal:
systemd-journal-remote ssh://some.host -o /tmp/dir
Retrieve locally stored events from a specific host and put them in a
journal file without compression:
systemd-journal-remote
/var/log/journal/12345678901234567890123456789012/
-o /tmp/uncompressed.journal --no-compress
NOTES
1. Journal Export Format
http://www.freedesktop.org/wiki/Software/systemd/export
systemd SYSTEMD-JOURNAL-RE(8)
---------------------------------------------------------------------------
_______________________________________________
systemd-devel mailing list
systemd-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/systemd-devel
