Merge pull request #2212 from rrobgill/man-pages

Man page for pilhole-FTL

automated install/basic-install.sh

@@ -1251,7 +1251,7 @@ installConfigs() {
 }
 
 install_manpage() {
-  # Copy Pi-hole man page and call mandb to update man page database
+  # Copy Pi-hole man pages and call mandb to update man page database
   # Default location for man files for /usr/local/bin is /usr/local/share/man
   # on lightweight systems may not be present, so check before copying.
   echo -en "  ${INFO} Testing man page installation"
@@ -1261,23 +1261,30 @@ install_manpage() {
     return
   elif [[ ! -d "/usr/local/share/man" ]]; then
     # appropriate directory for Pi-hole's man page is not present
-    echo -e "${OVER}  ${INFO} man page not installed"
+    echo -e "${OVER}  ${INFO} man pages not installed"
     return
-  elif [[ ! -d "/usr/local/share/man/man8" ]]; then
+  fi
+  if [[ ! -d "/usr/local/share/man/man8" ]]; then
     # if not present, create man8 directory
     mkdir /usr/local/share/man/man8
   fi
-  # Testing complete, copy the file & update the man db
+  if [[ ! -d "/usr/local/share/man/man5" ]]; then
-  cp ${PI_HOLE_LOCAL_REPO}/pihole.8 /usr/local/share/man/man8/pihole.8
+    # if not present, create man8 directory
+    mkdir /usr/local/share/man/man5
+  fi
+  # Testing complete, copy the files & update the man db
+  cp ${PI_HOLE_LOCAL_REPO}/manpages/pihole.8 /usr/local/share/man/man8/pihole.8
+  cp ${PI_HOLE_LOCAL_REPO}/manpages/pihole-FTL.8 /usr/local/share/man/man8/pihole-FTL.8
+  cp ${PI_HOLE_LOCAL_REPO}/manpages/pihole-FTL.conf.5 /usr/local/share/man/man5/pihole-FTL.conf.5
   if mandb -q &>/dev/null; then
     # Updated successfully
-    echo -e "${OVER}  ${TICK} man page installed and database updated"
+    echo -e "${OVER}  ${TICK} man pages installed and database updated"
     return
   else
     # Something is wrong with the system's man installation, clean up 
-    # our file, (leave everything how we found it).
+    # our files, (leave everything how we found it).
-    rm /usr/local/share/man/man8/pihole.8
+    rm /usr/local/share/man/man8/pihole.8 /usr/local/share/man/man8/pihole-FTL.8 /usr/local/share/man/man5/pihole-FTL.conf.5
-    echo -e "${OVER}  ${CROSS} man page db not updated, man page not installed"
+    echo -e "${OVER}  ${CROSS} man page db not updated, man pages not installed"
   fi
 }
 

automated install/uninstall.sh

@@ -173,7 +173,7 @@ removeNoPurge() {
 
     # If the pihole manpage exists, then delete and rebuild man-db
     if [[ -f /usr/local/share/man/man8/pihole.8 ]]; then
-        ${SUDO} rm -f /usr/local/share/man/man8/pihole.8
+        ${SUDO} rm -f /usr/local/share/man/man8/pihole.8 /usr/local/share/man/man8/pihole-FTL.8 /usr/local/share/man/man5/pihole-FTL.conf.5
         ${SUDO} mandb -q &>/dev/null
         echo -e "  ${TICK} Removed pihole man page"
     fi

manpages/pihole-FTL.8

@@ -0,0 +1,112 @@
+.TH "Pihole-FTL" "8" "pihole-FTL" "Pi-hole" "June 2018"
+.SH "NAME"
+pihole-FTL - Pi-hole : The Faster-Than-Light (FTL) Engine
+.br
+.SH "SYNOPSIS"
+\fBservice pihole-FTL \fR(\fBstart\fR|\fBstop\fR|\fBrestart\fR)
+.br
+
+\fBpihole-FTL debug\fR
+.br
+\fBpihole-FTL test\fR
+.br
+\fBpihole-FTL -v\fR
+.br
+\fBpihole-FTL -t\fR
+.br
+\fBpihole-FTL -b\fR
+.br
+\fBpihole-FTL -f\fR
+.br
+\fBpihole-FTL -h\fR
+.br
+\fBpihole-FTL dnsmasq-test\fR
+.br
+\fBpihole-FTL --\fR (\fBoptions\fR)
+.br
+
+.SH "DESCRIPTION"
+Pi-hole : The Faster-Than-Light (FTL) Engine is a lightweight, purpose-built daemon used to provide statistics needed for the Pi-hole Web Interface, and its API can be easily integrated into your own projects. Although it is an optional component of the Pi-hole ecosystem, it will be installed by default to provide statistics. As the name implies, FTL does its work \fIvery\fR \fIquickly\fR!
+.br
+
+Usage
+.br
+
+\fBservice pihole-FTL start\fR
+.br
+    Start the pihole-FTL daemon
+.br
+
+\fBservice pihole-FTL stop\fR
+.br
+    Stop the pihole-FTL daemon
+.br
+
+\fBservice pihole-FTL restart\fR
+.br
+    If the pihole-FTP daemon is running, stop and then start, otherwise start.
+.br
+
+Command line arguments
+.br
+
+\fBdebug\fR
+.br
+    Don't go into daemon mode (stay in foreground) + more verbose logging
+.br
+
+\fBtest\fR
+.br
+    Start FTL and process everything, but shut down immediately afterwards
+.br
+
+\fB-v, version\fR
+.br
+    Don't start FTL, show only version
+.br
+
+\fB-t, tag\fR
+.br
+    Don't start FTL, show only git tag
+.br
+
+\fB-b, branch\fR
+.br
+    Don't start FTL, show only git branch FTL was compiled from
+.br
+
+\fB-f, no-daemon\fR
+.br
+    Don't go into background (daemon mode)
+.br
+
+\fB-h, help\fR
+.br
+    Don't start FTL, show help
+.br
+
+\fBdnsmasq-test\fR
+.br
+    Test resolver config file syntax
+.br
+
+\fB--\fR  (options)
+.br
+    Pass options to internal dnsmasq resolver
+.br
+.SH "EXAMPLE"
+Command line arguments can be arbitrarily combined, e.g:
+.br
+
+\fBpihole-FTL debug test\fR
+.br
+
+Start ftl in foreground with more verbose logging, process everything and shutdown immediately
+.br
+.SH "SEE ALSO"
+\fBpihole\fR(8), \fBpihole-FTL.conf\fR(5)
+.br
+.SH "COLOPHON"
+
+Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net
+.br

manpages/pihole-FTL.conf.5

@@ -0,0 +1,102 @@
+.TH "pihole-FTL.conf" "5" "pihole-FTL.conf" "pihole-FTL.conf" "June 2018"
+.SH "NAME"
+
+pihole-FTL.conf - FTL's config file
+.br
+.SH "DESCRIPTION"
+
+/etc/pihole/pihole-FTL.conf will be read by \fBpihole-FTL(8)\fR on startup.
+.br
+
+\fBSOCKET_LISTENING=localonly|all\fR
+.br
+    Listen only for local socket connections or permit all connections
+.br
+
+\fBQUERY_DISPLAY=yes|no\fR
+.br
+    Display all queries? Set to no to hide query display
+.br
+
+\fBAAAA_QUERY_ANALYSIS=yes|no\fR
+.br
+    Allow FTL to analyze AAAA queries from pihole.log?
+.br
+
+\fBRESOLVE_IPV6=yes|no\fR
+.br
+    Should FTL try to resolve IPv6 addresses to host names?
+.br
+
+\fBRESOLVE_IPV4=yes|no\fR
+.br
+    Should FTL try to resolve IPv4 addresses to host names?
+.br
+
+\fBMAXDBDAYS=365\fR
+.br
+    How long should queries be stored in the database?
+.br
+    Setting this to 0 disables the database
+.br
+
+\fBDBINTERVAL=1.0\fR
+.br
+    How often do we store queries in FTL's database [minutes]?
+.br
+
+\fBDBFILE=/etc/pihole/pihole-FTL.db\fR
+.br
+    Specify path and filename of FTL's SQLite long-term database.
+.br
+    Setting this to DBFILE= disables the database altogether
+.br
+
+\fBMAXLOGAGE=24.0\fR
+.br
+    Up to how many hours of queries should be imported from the database and logs?
+.br
+    Maximum is 744 (31 days)
+.br
+
+\fBFTLPORT=4711\fR
+.br
+    On which port should FTL be listening?
+.br
+
+\fBPRIVACYLEVEL=0|1|2|3\fR
+.br
+    Which privacy level is used?
+.br
+    0 - show everything
+.br
+    1 - hide domains
+.br
+    2 - hide domains and clients
+.br
+    3 - paranoia mode (hide everything)
+.br
+
+\fBIGNORE_LOCALHOST=no|yes\fR
+.br
+    Should FTL ignore queries coming from the local machine?
+.br
+
+\fBBLOCKINGMODE=IP|IP-AAAA-NODATA|NXDOMAIN|NULL\fR
+.br
+    How should FTL reply to blocked queries?
+.br
+
+For each setting, the option shown first is the default.
+.br
+.SH "SEE ALSO"
+
+\fBpihole\fR(8), \fBpihole-FTL\fR(8)
+.br
+.SH "COLOPHON"
+
+Pi-hole : The Faster-Than-Light (FTL) Engine is a lightweight, purpose-built daemon used to provide statistics needed for the Pi-hole Web Interface, and its API can be easily integrated into your own projects. Although it is an optional component of the Pi-hole ecosystem, it will be installed by default to provide statistics. As the name implies, FTL does its work \fIvery quickly\fR!
+.br
+
+Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net
+.br

manpages/pihole.8

@@ -97,7 +97,6 @@ Available commands and options:
     Flush the Pi-hole log
 .br
 
-.br
 \fB-r, reconfigure\fR
 .br
     Reconfigure or Repair Pi-hole subsystems
@@ -130,7 +129,6 @@ Available commands and options:
       -l, privacylevel  <level> Set privacy level (0 = lowest, 3 = highest)
 .br
 
-.br
 \fB-c, chronometer\fR	[options]
 .br
     Calculates stats and displays to an LCD
@@ -178,13 +176,12 @@ Available commands and options:
 .br
       on                Enable the Pi-hole log at /var/log/pihole.log
 .br
-      off 		        Disable and flush the Pi-hole log at /var/log/pihole.log
+      off               Disable and flush the Pi-hole log at /var/log/pihole.log
 .br
       off noflush       Disable the Pi-hole log at /var/log/pihole.log
 .br
 
-.br
+\fB-up, updatePihole\fR [--check-only]
-\fB-up, updat\fBe\fR\fR\fBPihole\fR [--check-only]	
 .br
     Update Pi-hole subsystems
 .br
@@ -235,7 +232,6 @@ Available commands and options:
     Disable Pi-hole subsystems, optionally for a set duration
 .br
 
-.br
     (time options):	
 .br
       #s                Disable Pi-hole functionality for # second(s)
@@ -281,50 +277,43 @@ Some usage examples
 .br
     \fBpihole -b -d noads.example.com\fR  Remove "noads.example.com" from blacklist 
 .br
-    \fBpihole -wild example.com\fR            Add "example.com" as wildcard - would block ads.example.com, www.example.com etc.
+    \fBpihole -wild example.com\fR        Add "example.com" as wildcard - would block ads.example.com, www.example.com etc.
 .br
 
-    Changing the web ui password
+    Changing the Web Interface password
 .br
 
-.br
     \fBpihole -a -p ExamplePassword\fR    Change the password to "ExamplePassword"
 .br
 
     Updating lists from internet sources
 .br
 
-.br
     \fBpihole -g\fR                       Update the list of ad-serving domains
 .br
 
     Displaying version information
 .br
 
-.br
     \fBpihole -v -a -c\fR                 Display the current version of AdminLTE
 .br
 
-.br
     Temporarily disabling Pi-hole
 .br
 
-.br
     \fBpihole disable 5m\fR               Disable Pi-hole functionality for five minutes
 .br
 
-.br
     Switching Pi-hole subsystem branches
 .br
 
-.br
     \fBpihole checkout master\fR          Switch to master branch
 .br
     \fBpihole checkout core dev\fR        Switch to core development branch
 .br
 .SH "SEE ALSO"
 
-dnsmasq(8), lighttpd(8)
+\fBlighttpd\fR(8), \fBpihole-FTL\fR(8)
 .br
 .SH "COLOPHON"