Skip to content

Commit

Permalink
update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
tycho committed Dec 1, 2019
1 parent e641aa5 commit 3f1efae
Show file tree
Hide file tree
Showing 3 changed files with 113 additions and 62 deletions.
112 changes: 84 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,17 @@

## A (file-) journal for your shell

![Example session animation](images/shournal-example-session.gif)

#### What is it (good for)?
*TL;DR*:
* **Integrated tool** to increase the reproducibility of your work
on the shell: what did you do when and where and what files were modified/read.
* **Stand-alone tool** to monitor file events of a command/process (tree),
similar to <br>
`strace -f -e close $cmd`
but **a lot** faster.
but without the limitations imposed by ptrace-based solutions
and **a lot** faster.

*More details please*:

Expand All @@ -30,14 +33,25 @@ events it can be integrated really tight into the shell -
you won't even notice it (;
See also: [shell-integration](./shell-integration-scripts)

Besides output on the command-line in a human-readable format (or JSON)
you can export (parts of) your command-history into
a standalone html-file where it is displayed in an interactive
time-line-plot. Further miscellaneous statistics are displayed in
bar-plots, e.g. the commands with most file-modifications (see also above gif).


*shournal* runs only on GNU/Linux.


## Examples
Please note: below examples make use of the
[shell-integration](./shell-integration-scripts).<br>
Otherwise `shournal --exec $cmd` and
other boilerplate-code would have been necessary.
other boilerplate-code would have been necessary.
Instead of printing the `--query`-results to terminal, you can also create
fancy html-plots, by appending `--output-format html -o out.html`.
Use an ordinary web-browser for display.


* Create a file and ask shournal, how it came to be:
```
Expand Down Expand Up @@ -77,6 +91,27 @@ other boilerplate-code would have been necessary.


## Installation

### Binary releases
For Debian/Ubuntu-based distributions .deb-packages are available on the
[release-page](https://github.com/tycho-kirchner/shournal/releases/latest).
Only LTS-releases are supported, the packages are known to work on
Debian 9 (Stretch), Debian 10 (Buster) and Ubuntu 18.04 (Bionic).
Install deb-packages as usual, e.g.
`sudo apt install ./shournal_2.2_amd64.deb`

**After installation**:
To enable the shell-integration:

* for *bash*: put the following to the end of your ~/.bashrc
`source /usr/share/shournal/SOURCE_ME.bash`
and run `SHOURNAL_ENABLE` afterwards.
* for *other shells*: please open an issue, if you want your favorite
shell to be integrated as well (contributions welcome, zsh-support is planned).


### Compile and install from source

* Install gcc >= 5.0. Other compilers might work but are untested.
* Install cmake >=3.0.2 and make
* for safe generation of uuids it is recommend to install uuidd (uuid-runtime)
Expand All @@ -98,45 +133,59 @@ other boilerplate-code would have been necessary.
```
CentOS (note: CentOS 7 as of July 2019 only ships with gcc 4.8
-> compile gcc >= 5.0 yourself):
-> compile gcc >= 5.0 yourself. cmake3 and cmake are seperate packages
where cmake in version 2 is the default. Please ensure to compile with cmake3):
```
yum install gcc-c++ cmake make qt5-qtbase-devel libuuid-devel libcap-devel uuidd
yum install gcc-c++ cmake3 make qt5-qtbase-devel libuuid-devel libcap-devel uuidd
```
* In the source-tree-directory, enter the following commands to compile and install:
```
mkdir -p build
cd build
cmake .. # defaults to -DCMAKE_BUILD_TYPE=Release
# if you later want to generate a deb-package, it is recommended
# to use /usr as prefix: -DCMAKE_INSTALL_PREFIX=/usr
cmake ..
make
# as root:
make install
# or if using a Debian-based distribution, generate a .deb-package:
cpack -G DEB
```
* Depending on your distribution, additional steps might be necessary to
enable the (recommended) uuidd-daemon. If systemd is in use, one may need to:
```
systemctl enable uuidd
systemctl start uuidd
```
* if you plan on using the shell-integration, you'll need the location of
`libshournal-shellwatch.so` which is typically within /usr/local/lib/shournal
* Add a group to your system, which is primarily needed for the shell-integration:
**After compile and install**: if you created a .deb-package, please see
[Binary releases](###binary-releases). **Otherwise:**
* Add a group to your system, which is primarily needed for the shell-integration:
```groupadd shournalmsenter```
However, *do not add any users to that group*. It is part of a permission check, where root adopts that gid (within shournal).
If you don't like the default group name, you can specify your own: at build time pass the following to cmake:
```-DMSENTER_GROUPNAME=$your_group_name```
* Depending on your distribution, additional steps might be necessary to
enable the (recommended) uuidd-daemon. If systemd is in use, one may need to:
```
systemctl enable uuidd
systemctl start uuidd
```
* To **uninstall**, after having installed with `make install`, you can
execute
`xargs rm < install_manifest.txt`, but see
[here](https://stackoverflow.com/a/44649542/7015849) for the
limitations.
To enable the shell-integration: perform the same procedure as described
in [Binary releases](###binary-releases), however, the location of
the `SOURCE_ME.$shell_name` scripts after `make install` is typically
`/usr/local/share/shournal/`.
```groupadd shournalmsenter```
However, *do not add any users to that group*. It is part of a permission check, where root adopts that gid (within shournal).
If you don't like the default group name, you can specify your own: at build time pass the following to cmake:
```-DMSENTER_GROUPNAME=$your_group_name```
* Two executables were built: shournal and shournal-run. The latter is a setuid program, it has to be owned by root while having the setuid-bit set.
Typing `make install` as root does this automatically, to do so manually, enter as root:
```
chown root shournal-run
chmod u+s shournal-run
```
## FAQ
* **Does shournal track file rename/move operations?**<br>
Expand Down Expand Up @@ -299,6 +348,9 @@ For further limitations please visit the fanotify manpage.
## Credits
shournal makes use of great tools and libraries, most importantly the Qt-framework,
xxhash, tsl::ordered_map and cmake and also the Linux-Kernel's *fanotify*.
For the html-plot d3js, jquery, popper.js, bootstrap, webpack
and others are used.
Thanks to the developers!
The project arose as the practical part of my Bachelor thesis in computer science
Expand All @@ -310,10 +362,14 @@ Thanks for your great ideas and feedback!
# License
The whole project is licensed under the GPL, v3 or later
(see LICENSE file for details) **except** the libraries within
`extern/`: please refer to the licenses within their
respective directories.
(see LICENSE file for details)
**except**
* the libraries within
`extern/` → Please refer to the licenses within their
respective directories.
* The javascript-libraries in the auto-generated
`html-export/dist/main.js` → the licenses are
stored in `html-export/dist/main.licenses.txt`.
Copyleft (C) 2019, Tycho Kirchner
Binary file added images/shournal-example-session.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
63 changes: 29 additions & 34 deletions shell-integration-scripts/bash/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,43 +8,38 @@ of the above directory.


## Setup
* Install shournal (obviously)
* You'll need the location of shournal's shell integration shared library
(libshournal-shellwatch.so) which is typically at `/usr/local/lib/shournal`
* Download the [bash_integration.sh](./bash_integration.sh) (see above) and
put it into your favorite scripts-directory
* Add the following **to the end** of your .bashrc:
```
HISTCONTROL="ignoredups" # or anything other than "ignorespace" or "ignoreboth"
export SHOURNAL_PATH_LIB_SHELL_INTEGRATION="/PATH_TO/libshournal-shellwatch.so"
source /PATH_TO/bash_integration.sh
# SHOURNAL_ENABLE could also be called later, during the shell session:
SHOURNAL_ENABLE
```
**Note**: For testing purposes you might be tempted to enter above commands
manually within a shell-session. This does not work (straightforward).
For a quick test the following works:
```
$ export SHOURNAL_PATH_LIB_SHELL_INTEGRATION="/PATH_TO/libshournal-shellwatch.so"
$ LD_PRELOAD="$SHOURNAL_PATH_LIB_SHELL_INTEGRATION" bash
$ source /PATH_TO/bash_integration.sh
$ SHOURNAL_ENABLE
```

* Check, if *bash* is correctly observed:
```
$ echo foo > bar
$ shournal --query --wfile bar
# should output above command, etc.
```
It is assumed that shournal is already installed, as described in the
general [README](/../../) and that shournal's bash-integration functions
were already made available by sourcing the SOURCE_ME.bash
**at the end of ~/.bashrc** (below path may differ depending on
distribution and installation mode):
`source /usr/share/shournal/SOURCE_ME.bash`
**Note:** due to technical reasons the sourcing **must** be
performed in the bashrc and not within a terminal session.

Before successfully calling `SHOURNAL_ENABLE` you may
need to modify bash's history settings - in most
cases it should be sufficient to change `HISTCONTROL` to something
other than `ignorespace` or `ignoreboth`, for example:

`HISTCONTROL="ignoredups"`

Check, if *bash* is correctly observed:
```
$ SHOURNAL_ENABLE
$ echo foo > bar
$ shournal --query --wfile bar
# should output above command, etc.
```

## Notes
* As seen in *Setup*, the history-control of bash is modified. Background
is that shournal shall track *all* commands, which is currently
only possible, if all commands are saved to the history.
* **Never** modify the PROMPT_COMMAND after enabling shournal
(unless you know what you are doing (; )
* Background for shournal's bash-integration to forbid e.g. `ignorespace`
is that otherwise potentially wrong commands could be stored within
shournal's own history (the last command *not* beginning with
a space in this case).
Besides `HISTCONTROL` also
other variables like `HISTIGNORE` or `HISTSIZE` must be set appropriately.
shournal's bash integration checks those variables and gives hints, if
there is need for action.
* **Never** modify the PROMPT_COMMAND after enabling shournal
(unless you know what you are doing (; )

0 comments on commit 3f1efae

Please sign in to comment.