From 84aacc055a06faa1ab36fcf3064d84bd78d0ee0d Mon Sep 17 00:00:00 2001
From: Vito Caputo <vcaputo@pengaru.com>
Date: Wed, 25 Nov 2020 18:04:05 -0800
Subject: docs: add LICENSE and README files

Now there's even instructions and legalese
---
 README | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README

(limited to 'README')

diff --git a/README b/README
new file mode 100644
index 0000000..4a636dc
--- /dev/null
+++ b/README
@@ -0,0 +1,97 @@
+## Overview
+
+ jio is an experimental systemd-journald journal file tool
+ 
+ It deliberately avoids using systemd's sd-journal interface, instead
+ directly interfacing with journal files as defined by:
+
+ https://github.com/systemd/systemd/blob/v246/docs/JOURNAL_FILE_FORMAT.md
+
+ This is an unfinished work-in-progress, use at your own risk, backup your
+ journals before using.
+
+
+## Author, License, and Contributing
+
+ jio is written by Vito Caputo <vcaputo@pengaru.com>.
+ 
+ jio is licensed under the terms of the General Public License v3.
+
+ jio patches are welcome, just email them to <vcaputo@pengaru.com>.
+
+ Discussion of systemd-journald or the underlying journal file format
+ should occur on the systemd-devel mailing list.  Spare the systemd-devel
+ list of discussion specifically about jio patches, bugs, code, or
+ programming style, stuff that doesn't relate to systemd-journald or
+ journal-file at all should be sent directly to the jio author.
+
+
+## Requirements
+
+ jio utilizes the new "io_uring" Linux kernel interface, technically
+ introduced in v5.1, but v5.9+ is recommended for io_uring.  It's enabled
+ in the kernel config with CONFIG_IO_URING=Y, easily confirmed by checking
+ /proc/config.gz if present.
+
+ The liburing library is used for accessing the low-level io_uring syscalls
+ and preparing the associated queue entries.  You can find the source at:
+
+ https://git.kernel.dk/cgit/liburing
+
+ Otherwise jio is a relatively boring C program using autotools for its
+ build system.
+
+
+## Building
+
+ To build jio from source, first ensure you've cloned the git repository
+ recursively, including submodules:
+ 
+ `git clone --recursive git://git.pengaru.com/jio`
+ 
+ Also ensure you have a working C compiler, liburing, and autotools
+ available on the build host.
+ 
+ Bootstrap the build system from the jio source dir:
+ 
+ `./bootstrap`
+ 
+ Then configure and make from a build subdirectory:
+ 
+ `mkdir build && cd build && ../configure && make`
+ 
+ Assuming all goes well, you should have a jio executable at
+ "build/src/jio".
+
+ jio may be run as a regular user without elevated privileges, provided the
+ journal files of interest are accessible, like user journal files.  To
+ access system journal files generally requires elevated privileges.
+
+
+## Usage
+
+ Simply running `jio` with no arguments will print a terse summary of
+ key subcommands, e.g.:
+
+ ```
+ $ src/jio
+ Usage: build/src/jio {help,reclaim,report} [subcommand-args]
+ $
+ ```
+
+ This document is unlikely to be kept up to date as available subcommands
+ evolve, so it's best to just run jio without any arguments to see what's
+ possible.  `jio help` may also show additional subcommands.
+
+ At this time, the report subcommand features should be considered safe,
+ and if you run it as your regular user it will be limited to only journals
+ your user has access to.  If you run it as root, it will open all
+ available journals.
+
+ The reclaim subcommand is a journal-modifying command, so it should be
+ treated with caution especially considering the experimental nature of
+ jio.
+
+ Generally speaking, make backup copies of your journals before using jio
+ in any of its journal-modifying modes, only disposing of them after you've
+ verified the results are desirable.
-- 
cgit v1.2.3