Merge pull request #2205 from rrobgill/manual-page

Manual page

automated install/basic-install.sh

@@ -1193,6 +1193,37 @@ installConfigs() {
   fi
 }
 
+install_manpage() {
+  # Copy Pi-hole man page 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"
+  if ! command -v mandb &>/dev/null; then
+    # if mandb is not present, no manpage support
+    echo -e "${OVER}  ${INFO} man not installed"
+    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"
+    return
+  elif [[ ! -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
+  cp ${PI_HOLE_LOCAL_REPO}/pihole.8 /usr/local/share/man/man8/pihole.8
+  if mandb -q &>/dev/null; then
+    # Updated successfully
+    echo -e "${OVER}  ${TICK} man page 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).
+    rm /usr/local/share/man/man8/pihole.8
+    echo -e "${OVER}  ${CROSS} man page db not updated, man page not installed"
+  fi
+}
+
 stop_service() {
   # Stop service passed in as argument.
   # Can softfail, as process may not be installed when this is called
@@ -1695,6 +1726,9 @@ installPihole() {
     configureFirewall
   fi
 
+  # install a man page entry for pihole
+  install_manpage
+
   # Update setupvars.conf with any variables that may or may not have been changed during the install
   finalExports
 }

automated install/uninstall.sh

@@ -171,6 +171,13 @@ removeNoPurge() {
         echo -e "${OVER}  ${TICK} Removed pihole-FTL"
     fi
 
+    # 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} mandb -q &>/dev/null
+        echo -e "  ${TICK} Removed pihole man page"
+    fi
+
     # If the pihole user exists, then remove
     if id "pihole" &> /dev/null; then
         if ${SUDO} userdel -r pihole 2> /dev/null; then

pihole.8

@@ -0,0 +1,332 @@
+.TH "Pi-hole" "8" "Pi-hole" "Pi-hole" "May 2018"
+.SH "NAME"
+
+Pi-hole : A black-hole for internet advertisements
+.br
+.SH "SYNOPSIS"
+
+\fBpihole\fR (\fB-w\fR|\fB-b\fR|\fB-wild\fR) [options] domain(s)
+.br
+\fBpihole -a\fR \fB-p\fR password
+.br
+\fBpihole -a\fR (\fB-c|-f|-k\fR)
+.br
+\fBpihole -a\fR [\fB-r\fR hostrecord]
+.br
+\fBpihole -a -e\fR email
+.br
+\fBpihole -a -i\fR interface
+.br
+\fBpihole -a -l\fR privacylevel
+.br
+\fBpihole -c\fR [-j|-r|-e]
+.br
+\fBpihole\fR \fB-d\fR [-a] 
+.br
+\fBpihole -f
+.br
+pihole -r
+.br
+pihole -t 
+.br
+pihole -g\fR
+.br
+\fBpihole\fR -\fBq\fR [options]
+.br
+\fBpihole\fR \fB-l\fR (\fBon|off|off noflush\fR)
+.br
+\fBpihole -up \fR[--checkonly]
+.br
+\fBpihole -v\fR [-p|-a|-f] [-c|-l|-hash]
+.br
+\fBpihole uninstall
+.br
+pihole status
+.br
+pihole restartdns\fR
+.br
+\fBpihole\fR (\fBenable\fR|\fBdisable\fR [time])
+.br
+\fBpihole\fR \fBcheckout\fR repo [branch]
+.br
+\fBpihole\fR \fBhelp\fR
+.br
+.SH "DESCRIPTION"
+
+Available commands and options:
+.br
+
+\fB-w, whitelist\fR [options] [<domain1> <domain2 ...>]
+.br
+    Adds or removes specified domain or domains tho the Whitelist
+.br
+
+\fB-b, blacklist\fR [options] [<domain1> <domain2 ...>]
+.br
+    Adds or removes specified domain or domains to the blacklist
+.br
+
+\fB-wild, wildcard\fR [options] [<domain1> <domain2 ...>]
+.br
+    Add or removes specified domain, and all subdomains to the blacklist
+.br
+
+    (Whitelist/Blacklist manipulation options):
+.br
+      -d, --delmode     Remove domain(s) from the list
+.br
+      -nr, --noreload   Update list without refreshing dnsmasq
+.br
+      -q, --quiet       Make output less verbose
+.br
+      -l, --list        Display all your listed domains
+.br
+      --nuke            Removes all entries in a list
+.br
+
+\fB-d, debug\fR [-a]	
+.br
+    Start a debugging session 
+.br
+
+      -a                Enable automated debugging
+.br
+
+\fB-f, flush\fR
+.br
+    Flush the Pi-hole log
+.br
+		
+.br
+\fB-r, reconfigure\fR
+.br
+    Reconfigure or Repair Pi-hole subsystems
+.br
+
+\fB-t, tail\fR
+.br
+    View the live output of the Pi-hole log
+.br
+
+\fB-a, admin\fR [options]
+.br
+
+    (Admin options):
+.br
+      -p, password      Set Web Interface password
+.br
+      -c, celsius       Set Celsius as preferred temperature unit
+.br
+      -f, fahrenheit    Set Fahrenheit as preferred temperature unit
+.br
+      -k, kelvin        Set Kelvin as preferred temperature unit
+.br
+      -r, hostrecord    Add a name to the DNS associated to an IPv4/IPv6 address
+.br
+      -e, email         Set an administrative contact address for the Block Page
+.br
+      -i, interface     Specify dnsmasq's interface listening behavior
+.br
+      -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 
+.br
+
+    (Chronometer Options):
+.br
+      -j, --json        Output stats as JSON formatted string
+.br
+      -r, --refresh     Set update frequency (in seconds)
+.br
+      -e, --exit        Output stats and exit witout refreshing
+.br
+
+\fB-g, updateGravity\fR	
+.br
+    Update the list of ad-serving domains
+.br
+
+\fB-q, query\fR [option]	
+.br
+    Query the adlists for a specified domain
+.br
+
+    (Query options):
+.br
+      -adlist           Print the name of the block list URL
+.br
+      -exact            Search the block lists for exact domain matches
+.br
+      -all              Return all query matches within a block list
+.br
+
+\fB-h, --help, help\fR	
+.br
+    Show a help dialog
+.br
+
+\fB-l, logging\fR [on|off|off noflush]	
+.br
+    Specify whether the Pi-hole log should be used 
+.br
+
+	(Logging 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
+.br
+      off noflush       Disable the Pi-hole log at /var/log/pihole.log
+.br
+	
+.br
+\fB-up, updat\fBe\fR\fR\fBPihole\fR [--check-only]	
+.br
+    Update Pi-hole subsystems 
+.br
+
+      --check-only      Exit script before update is performed.
+.br
+
+\fB-v, version\fR [repo] [options]	
+.br
+    Show installed versions of Pi-hole, Web Interface &amp; FTL
+.br
+ 
+.br
+    (repo options):
+.br
+      -p, --pihole      Only retrieve info regarding Pi-hole repository
+.br
+      -a, --admin       Only retrieve info regarding AdminLTE repository
+.br
+      -f, --ftl         Only retrieve info regarding FTL repository
+.br
+    (version options):
+.br
+      -c, --current     Return the current version
+.br
+      -l, --latest      Return the latest version
+.br
+      --hash            Return the Github hash from your local repositories
+.br
+
+\fBuninstall\fR
+.br
+    Uninstall Pi-hole from your system
+.br
+
+\fBstatus\fR
+.br
+    Display the running status of Pi-hole subsystems
+.br
+
+\fBenable\fR
+.br
+    Enable Pi-hole subsystems
+.br
+
+\fBdisable\fR [time]
+.br
+    Disable Pi-hole subsystems, optionally for a set duration
+.br
+		
+.br
+    (time options):	
+.br
+      #s                Disable Pi-hole functionality for # second(s)
+.br
+      #m                Disable Pi-hole functionality for # minute(s)
+.br
+
+\fBrestartdns\fR
+.br
+    Restart Pi-hole subsystems
+.br
+
+\fBcheckout\fR [repo] [branch]	
+.br
+    Switch Pi-hole subsystems to a different Github branch
+.br
+
+    (repo options):
+.br
+      core              Change the branch of Pi-hole's core subsystem
+.br
+      web               Change the branch of Admin Console subsystem
+.br
+      ftl               Change the branch of Pi-hole's FTL subsystem
+.br
+    (branch options):
+.br
+      master            Update subsystems to the latest stable release
+.br
+      dev               Update subsystems to the latest development release
+.br
+      branchname        Update subsystems to the specified branchname
+.br
+.SH "EXAMPLE"
+
+Some usage examples
+.br
+
+    Whitelist/blacklist manipulation
+.br
+
+    \fBpihole -w iloveads.example.com\fR  Add "iloveads.example.com" to whitelist
+.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.
+.br
+
+    Changing the web ui 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)
+.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