Add manpages and INSTALL.md guide file

Manual pages for nice-lad and nice_lad.conf added in section 8.

Change-Id: Ie8a0f2503de6541a970bf483cc54a0c4c05ee8ae

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0ec72ea..b8ff06e 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -76,3 +76,6 @@ IF(WITH_TESTS)
     SET(TARGET_NICE_LAD_TESTS "nice-lad-tests")
     ADD_SUBDIRECTORY(tests)
 ENDIF(WITH_TESTS)
+
+SET(TARGET_NICE_LAD_DOCS "nice-lad-docs")
+ADD_SUBDIRECTORY(docs)

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644 (file)
index 0000000..e3796ef
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,47 @@
+# nice-lad
+
+## Building requirements
+* CMake >= 2.8.3
+* Boost >= 1.57
+* Audit >= 2.4.3
+* gmock >= 1.7.0 -- required for tests only
+* gcc >= 4.8.3 or clang >= 3.4
+
+## The project was tested using following compilers (Linux distributions)
+* gcc 5.1.1 (Fedora 22)
+* clang 3.5.0 (Fedora 22)
+* gcc 4.9 (Tizen)
+* gcc 4.8.4 (Ubuntu 14.04)
+* clang 3.4 (Ubuntu 14.04)
+
+## Building
+Following commands should be performed in the source directory.
+```sh
+mkdir build
+cd build
+# With tests
+cmake .. [ -DGMOCK_ROOT=/path/to/gmock/root/directory ] [ -DCMAKE_BUILD_TYPE=<mode> ]
+# Without tests
+cmake .. -DWITH_TESTS=OFF [ -DCMAKE_BUILD_TYPE=<mode> ]
+make
+```
+
+### Build modes
+Possible build modes are: RELEASE, DEBUG, CCOV (enables code coverage) and PROFILING
+(enables code profiling).
+
+## Installing
+```sh
+make install
+```
+To change installing location (add prefix) use CMAKE_INSTALL_PREFIX flag to cmake.
+
+## Files
+The package consists of following files (note, the exact paths are
+system-dependent):
+
+* /etc/audisp/plugins.d/nice_lad.conf
+* /usr/sbin/nice-lad
+* /usr/share/man/man8/nice-lad.8.gz
+* /usr/share/man/man8/nice_lad.conf.8.gz
+

diff --git a/README.md b/README.md
index 53b029b..52819d7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -31,7 +31,6 @@ The equivalent places, nice-lad can be obtained from:
 * [Tizen](https://review.tizen.org/gerrit/gitweb?p=platform/core/security/nice-lad.git)
 * [GitHub](https://github.com/Samsung/nice-lad)
 
-
 ## Features
 Nice-lad, as an audisp plugin, is fed with audit events. It parses and filters
 them to obtain and aggregate information useful in context of logging of access
@@ -56,18 +55,8 @@ Nice-lad uses:
 
 [5]: https://github.com/Samsung/security-manager "Security Manager"
 
-
-## Running the project
-The package consists of following files (note, the exact paths are
-system-dependent):
-
-* /etc/audisp/plugins.d/nice_lad.conf,
-* /usr/sbin/nice-lad.
-
-Provided, the above config file is present in audisp plugins directory, nice-lad
-is automagically activated, when auditing service is run. In order to disable
-nice-lad, while keeping audit running, one need to edit the config to contain
-"active = no".
+## Running and configuration
+Please refer to INSTALL.md file for installation and configuration guide.
 
 ### Reading the logs
 Nice-lad will log access denials to journald (if available) or syslog with
@@ -85,3 +74,18 @@ Nice-lad comes with a set of unit tests written in [gmock][6]. By adding new
 features or fixing bugs, please add or update tests.
 
 [6]: http://gmock.org/ "Gmock"
+
+## Usage
+Nice-lad is automatically started by audispd service. To disable auto-starting
+by audispd service, change "active" to "no" in nice-lad.conf file in audisp
+plugins directory: "/etc/audisp/plugins.d/nice_lad.conf"[^1].
+To change collector (backend) log level, set "arg = -l LOG_LEVEL". Possible log
+levels are defined in [syslog(3)][7]. Default collector log level is LOG_INFO.
+Nice-lad can be manually started with -h/--help parameter to print help message.
+If ran with invalid parameter, it will be terminated and error will be logged to
+journald or syslog[^2].
+
+[^1]: Paths are distribution-specific and resolved at building time.
+[^2]: Depends on backend resolved at building time.
+
+[7]: http://linux.die.net/man/3/syslog "syslog(3)"

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
new file mode 100644 (file)
index 0000000..85505b6
--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,2 @@
+INSTALL(FILES nice-lad.8 DESTINATION /usr/share/man/man8 COMPONENT doc)
+INSTALL(FILES nice_lad.conf.5 DESTINATION /usr/share/man/man5 COMPONENT doc)

diff --git a/docs/nice-lad.8 b/docs/nice-lad.8
new file mode 100644 (file)
index 0000000..533e9ea
--- /dev/null
+++ b/docs/nice-lad.8
@@ -0,0 +1,45 @@
+.TH nice-lad 8 "04 Aug 2015"
+
+.SH NAME
+\fBnice-lad\fR \- \fBN\fRarcissistic, \fBI\fRncredible, \fBC\fRompletely \fBE\fRxceptional
+\fBL\fRogger of \fBA\fRccess \fBD\fRenials
+
+.SH SYNOPSIS
+\fBnice-lad\fR [\fB-l\fR, \fB--collector-log-level\fR \fILOG_LEVEL\fR] | [\fB-h\fR, \fB--help\fR]
+
+.SH DESCRIPTION
+Nice-lad is a tool to collect logs of access denials in system. As an audispd(8) plugin, it
+is fed with audit events. It parses and filters them to obtain and aggregate
+information useful in context of access denials logging.
+
+At the moment, the supported subsystems are:
+  * DAC denials on given groups
+  * Smack denials
+  * Cynara denials
+  * Netfilter denials (supported by Nether)
+
+.SH OPTIONS
+.TP
+.BR \fB-h\fR ", " \fB--help\fR
+prints help message
+
+.TP
+.BR \fB-l\fR ", " \fB--collector-log-level\fR " " \fILOG_LEVEL\fR
+sets collector log level. Possible log levels are defined in syslog(3)
+
+.SH CONFIGURATION
+See nice_lad.conf(5) man page.
+
+.SH SEE ALSO
+audispd(8), syslog(3), nice_lad.conf(5)
+
+.SH REPORTING BUGS
+Please report bugs to \fIhttps://bugs.tizen.org\fR or
+\fIhttps://github.com/Samsung/nice-lad/issues\fR
+
+.SH LICENSE
+Nice-lad is licensed under Apache License Version 2.0, January 2004 available at
+\fIhttp://www.apache.org/licenses/\fR
+
+.SH AUTHOR
+Aleksander Zdyb <a.zdyb@samsung.com>

diff --git a/docs/nice_lad.conf.5 b/docs/nice_lad.conf.5
new file mode 100644 (file)
index 0000000..4740291
--- /dev/null
+++ b/docs/nice_lad.conf.5
@@ -0,0 +1,21 @@
+.TH nice_lad.conf 5 "04 Aug 2015"
+
+.SH NAME
+nice_lad.conf \- nice-lad configuration file for audispd(8) service
+
+.SH DESCRIPTION
+File is located in audispd(8) plugins directory. It is posible to disable
+auto-starting nice-lad by audispd(8) and change collector log level.
+
+.SH CONFIGURATION
+.TP
+.BR \fBactive\fR " " = " " < " " \fIyes\fR " " | " " \fIno\fR " " >
+indicates if nice-lad will be auto-ran by audispd(8)
+
+.TP
+.BR \fR[ " " \fBargs\fR " " = " " -l " " \fILOG_LEVEL\fR " "]
+sets collector (backend) log level to \fILOG_LEVEL\fR. Possible log levels are defined in
+syslog(3). Default log level is \fILOG_INFO\fR.
+
+.SH SEE ALSO
+audispd(8), nice-lad(8), syslog(3)

diff --git a/packaging/nice-lad-docs.manifest b/packaging/nice-lad-docs.manifest
new file mode 100644 (file)
index 0000000..86dbb26
--- /dev/null
+++ b/packaging/nice-lad-docs.manifest
@@ -0,0 +1,5 @@
+<manifest>
+    <request>
+        <domain name="_" />
+    </request>
+</manifest>

diff --git a/packaging/nice-lad.spec b/packaging/nice-lad.spec
index 596d8d9..b290e6e 100644 (file)
--- a/packaging/nice-lad.spec
+++ b/packaging/nice-lad.spec
@@ -6,7 +6,8 @@ Group:      Security/Access Control
 License:    Apache-2.0
 Source0:    %{name}-%{version}.tar.gz
 Source1001:    %{name}.manifest
-Source1002:    nice-lad-tests.manifest
+Source1002:    %{name}-tests.manifest
+Source1003:    %{name}-docs.manifest
 BuildRequires: boost-devel
 BuildRequires: cmake
 BuildRequires: pkgconfig(audit)
@@ -35,10 +36,17 @@ BuildRequires: pkgconfig(gmock)
 Unit tests for nice-lad. A standalone application checking correctness
 of nice-lad's components.
 
+%package docs
+Summary:    Man pages for nice-lad
+
+%description docs
+Manual pages for nice-lad and nice_lad.conf file.
+
 %prep
 %setup -q
 cp -a %{SOURCE1001} .
 cp -a %{SOURCE1002} .
+cp -a %{SOURCE1003} .
 
 %build
 %if 0%{?sec_build_binary_debug_enable:1}
@@ -75,8 +83,13 @@ rm -rf %{buildroot}
 %attr(755,root,root) %{_sbindir}/%{name}
 %config %{_sysconfdir}/audisp/plugins.d/nice_lad.conf
 
-%files -n nice-lad-tests
-%manifest nice-lad-tests.manifest
+%files -n %{name}-tests
+%manifest %{name}-tests.manifest
 %license LICENSE
-%attr(755,root,root) %{_bindir}/nice-lad-tests
+%attr(755,root,root) %{_bindir}/%{name}-tests
 
+%files -n %{name}-docs
+%manifest %{name}-docs.manifest
+%license LICENSE
+%attr(644,root,root) %{_mandir}/man8/nice-lad.8.gz
+%attr(644,root,root) %{_mandir}/man5/nice_lad.conf.5.gz