diff --git a/LICENCE b/LICENCE new file mode 100644 index 0000000000000000000000000000000000000000..a15297aa57a9b0e4788f83f43135ae2fad9cba3f --- /dev/null +++ b/LICENCE @@ -0,0 +1,19 @@ +Copyright 2017 Dominik George <d.george@tarent.de> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to +deal in the Software without restriction, including without limitation the +rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..7b32ee0ab66c9f4c587eb5df15fb3e28d90e88c0 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +Universal strace wrapper for debugging +====================================== + +stracify is a universal strace wrapper for debugging purposes. It replaces +an arbitrary binary with itself, ensuring it will be called as close to the +original as possible, and also includes some management code to wrap or +unwrap binaries. + +Installation +============ + +Install mksh as a dependency, then install the stracify script into the +PATH. + +Wrapping a binary +================= + +Wrapping a binary is done using the command `sudo stracify /usr/bin/foo`. + +An optional strace filter expression can be passed, like `sudo stracify +/usr/bin/foo open,write`. + +On Debian systems, care is taken to register the diversion with dpkg. + +Finding the strace output of calls +================================== + +The output fiels are stored in a directory structure organised like this: + +``` +/var/log/stracify/ + |- usr_bin_foo/ + |- root/ + |- strace_2017-09-08T14:19:57+02:00_11911.log.11924 + |- user1/ + |- ... +``` + +This structure was chosen so all users can run the wrapped binary, but +without opening up the strace outputs from one user's calls to others. The +template for the log file names is `strace_$date_$pif.$childpid`. + +Please note that due to the architecture of stracify, the logs will contain +quite a bit of trace from stracify and mksh themselves. This is not very +pretty, but better than losing functionality in the wrapped binary due to a +crooked call. + +Unwrapping a binary +=================== + +A binary can be unwrapped using the command `stracify unwrap /usr/bin/foo`.