diff --git a/automated install/basic-install.sh b/automated install/basic-install.sh index 91589914..325688cd 100755 --- a/automated install/basic-install.sh +++ b/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 } diff --git a/automated install/uninstall.sh b/automated install/uninstall.sh index 0a51fd4a..4525f42f 100755 --- a/automated install/uninstall.sh +++ b/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 diff --git a/pihole.8 b/pihole.8 new file mode 100644 index 00000000..76d6b72b --- /dev/null +++ b/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] [ ] +.br + Adds or removes specified domain or domains tho the Whitelist +.br + +\fB-b, blacklist\fR [options] [ ] +.br + Adds or removes specified domain or domains to the blacklist +.br + +\fB-wild, wildcard\fR [options] [ ] +.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 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 & 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