README

PHP Scanner Server
	by pqwoerituytrueiwoq (at) ubuntuforums.org
Based on Linux Scanner Server 1.2 Beta
	by PHiLLIP KLiEWER (http://scannerserver.online02.com)

Released under the GPL 2.0

Last Update: 6/17/2020 (Month/Day/Year)
For Version: 1.7-19_dev

Change Log:
	https://github.com/GM-Script-Writer-62850/PHP-Scanner-Server/wiki/Change-Log

PHP Linux Scanner Server is a PHP web application that allows you to share multiple scanners (supported by SANE) over a network.

The following packages need to be installed:
* imagemagick (6.5.9+)     - For image conversion
* sane-utils               - For accessing scanners
* usbutils                 - For updating the device path of scanners using libusb
* apache2                  - A web server
* libapache2-mod-php       - Ubuntu 16.04 + | Enables PHP to run under apache2
* coreutils                - For various purposes, not having this would probably result in an unusable system
* php5                     - For running php
* php                      - Ubuntu 16.04 + | For running php
* php5-json                - For storing/transferring/parsing data (If this package is not available, it may already be part of php5)
* php-json                 - Ubuntu 16.04 + | For storing/transferring/parsing data (If this package is not available, it may already be part of php5)
+ php5-curl                - For uploading scans to imgur.com
+ php-curl                 - Ubuntu 16.04 + | For uploading scans to imgur.com
+ tesseract-ocr            - For image to text conversion
+ tar                      - For downloading a copy of PHP Linux Scanner Server in .tar.lzma format (link in footer)
+ zip                      - For downloading a compressed scan
+ php-fpdf                 - For downloading a pdf file
+ libpaper-utils           - For detecting paper sizes
+ sed                      - Used in the fall-back method of detecting tesseract languages
+ grep                     - Used in the fall-back method of detecting tesseract languages
_ hplip                    - Required for HP scanner support
_ cups                     - Required if you want to use the printer service
_ php5-cli                 - For running php from command line
_ php-cli                  - Ubuntu 16.04 + | For running php from command line
_ curl                     - For making url request via command line through the network (alternative to php5-cli)
_ tesseract-ocr-all        - All Language packages for tesseract
_ tesseract-ocr-*          - Language packages for tesseract
_ fortune                  - For displaying fortunes in the debug console
_ cowsay                   - For wrapping fortunes in ASCII art
	* Mandatory
	+ Recommended for full functionality
	_ Optional or required for full functionality

	Some of these will likely already be installed, some newer distros (ubuntu 13.10) will require php5-json
	Starting with Ubuntu 16.04 libapache2-mod-php is not pulled by php, php5 has been changed to php7.0, there is a php meta package

	sudo apt-get install imagemagick sane-utils usbutils apache2 php libapache2-mod-php php-json php-curl php-fpdf tesseract-ocr tar zip libpaper-utils grep sed coreutils

Permissions:
	The user www-data needs write permissions to the following folders
		./scans/file
		./scans/thumb
		./config
		./config/parallel

Security Notes:
	Anyone with access to the scanner can view all your scans
	Do not give www-data more permission than needed, there may be security holes (If you find any let me know, they are bugs)

Supported Browsers:
	Firefox (recommended)
		http://www.mozilla.org/en-US/firefox/all.html
	Google Chrome
		https://www.google.com/chrome
	Chromium
		http://www.chromium.org/getting-involved/dev-channel
	Safari
		http://www.apple.com/safari/download/
	Opera (NOT Opera Mini)
		http://www.opera.com/browser/
	Microsoft Edge
		https://www.microsoft.com/en-us/edge
	IE 11
		https://www.microsoft.com/en-us/download/details.aspx?id=41628

Enabling Auto-Deletion of old scans:
	cleaner.php: Old scan auto-deletion tool.
		http://ubuntuforums.org/showpost.php?p=10294835&postcount=37

	Basically run this command
		crontab -e
	then add this line (if you need root here use `sudo crontab -e`)
		*/5 * * * * php -f /path/to/cleaner.php
	or this line (Will not require root unless you want it to work when you are not loged in)
		*/5 * * * * curl http://localhost/path/to/cleaner.php

	It will Check every 5 minutes for scans older than 1 day (86400 seconds value
		in cleaner.php) and deletes them.

Frequently asked questions/issues:
	Why is there a 404 error while trying to display a 404 error
		Apparently you are running the server in a sub-folder on the domain, you will need to edit .htaccess with the full path relative to the root document
		Basically if you put the server in /var/www/scanner/ you need to put /scanner before /inc in the .htaccess file
	Sometimes when I download a large file I get nothing (a 0 byte file)
		You will need to increase the max memory PHP can use, 
			To do this run this command (path varies depending on php version, there are two formats):
				cat /etc/php5/apache2/php.ini -n| grep memory_limit
				cat /etc/php/7.4/apache2/php.ini -n| grep memory_limit
			You will see something like this:
				407	memory_limit = 128M
			407 is the line number the setting is on
			We need to change the 128 to a higher number
			Open up /etc/php5/apache2/php.ini as root and change the number
			I am not sure how high you will need it, I have had issues with files under 60MB hitting the 128MB limit (total usage was under 45% of the limit)
			I set mine to 1024 (1 GiB) if you need more memory than you have ram be sure your swap partition is large enough to cover the overdraw
	The debug console shows a error when it runs convert, something about 'convert-im6.q16: no images defined'
		This can happen when high res images or PDF files, please take a look at this:
			https://askubuntu.com/questions/1181762/imagemagickconvert-im6-q16-no-images-defined
	What is bug 13, it is mentioned in the debug console
		https://github.com/GM-Script-Writer-62850/PHP-Scanner-Server/issues/13
	Why don't you have a .deb, .rpm, etc file I can install
		This more like an addon than a program so I am not sure if one of those would be appropriate, I have written bash
		scripts to install and update this, you can find them on the Downloads page in the Wiki
			https://github.com/GM-Script-Writer-62850/PHP-Scanner-Server/wiki/Downloads
	The brightness and contrast options do not work on lucid lynx.
		This is because lucid has ImageMagick 6.5.7-8 and the brightness-contrast option was added in version 6.5.9
			64Bit:
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086531/+files/libmagickcore3_6.6.2.6-1ubuntu1.1_amd64.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086531/+files/libmagickwand3_6.6.2.6-1ubuntu1.1_amd64.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086531/+files/libmagick%2B%2B3_6.6.2.6-1ubuntu1.1_amd64.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086531/+files/imagemagick_6.6.2.6-1ubuntu1.1_amd64.deb
			32Bit:
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086533/+files/libmagickcore3_6.6.2.6-1ubuntu1.1_i386.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086533/+files/libmagickwand3_6.6.2.6-1ubuntu1.1_i386.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086533/+files/libmagick%2B%2B3_6.6.2.6-1ubuntu1.1_i386.deb
				https://launchpad.net/~ubuntu-security/+archive/ppa/+buildjob/2086533/+files/imagemagick_6.6.2.6-1ubuntu1.1_i386.deb
	Why should I enable auto delete?
		So your Hard Drive does not end up full of scans
	What does EOL stand for 
		End Of Life, meaning it will no longer receive updates
	Every time I load a page it is blank.
		Somehow there is an error somewhere, check your apache error log
			for me the file was located at
				/var/log/apache2/error.log
			You can set php to show the error in the browser by editing your php.ini
			for me it was located in 
				/etc/php5/apache2/php.ini
			then find this line
				display_errors = Off
			and set it to On (it was on line 531 for me) 
			at this point apache will need a reload (sudo service apache2 reload)
		If the error was not caused by you not reading the instructions please file a bug report
	The conversion to text was very poor/blank
		Try making the image larger the text is probably too small for tesseract-ocr to read
	How can I change the low disk space warning threshold
		It is set on line 3 of index.php
	How can I turn the auto update checker off
		It is set on line 6 of index.php
	How can I change the time files are kept with auto-delete enabled
		Open cleaner.php and change the 86400 on line 2 to a different number (86400 is one day in seconds)
			You can use math there and put 86400*7 to make it a week
	I see my scanner with the command "scanimage -L" but it is not being detected
		This is a permissions issue (and a royal pita)
			http://127.0.0.1/index.php?page=Access%20Enabler (link works after installing)
			http://jhansonxi.blogspot.com/2010/10/scanner-access-enabler.html
		If that site goes the access enabler is included with this (1.2 lacks a desktop file)
			scanner-access-enabler-1.1.tar.bz2 (http://www.mediafire.com/?86e6ykeueodu7tl)
			scanner-access-enabler-1.2.tar.bz2 (http://www.mediafire.com/?p1plimo2yf31kl3)
			scanner-access-enabler-1.4.tar.bz2 (http://www.mediafire.com/?4r1aw9ix9ayb0u0)
	Why can't I change the orientation on the scan page
		because the selected paper size will only fit in the scanner one way
	Why is the pdf download (single page) not working I keep getting a file with a error in it
		The script assumes fpdf.php is located in /usr/share/php/fpdf/ this is set on line 2 of download.php
	Why is it hanging up when I search for printers
		It assumes all found printers are connected to the computer, lpoptions seems to hang when the printer it is looking for is not there
	How do I increase the max upload size for PDFs?
		You need to edit your php.ini file
			for me it was located in 
				/etc/php5/apache2/php.ini
			You will need to change the post_max_size and upload_max_filesize
			For me they were on lines 673 and 805
			If post_max_size is the lower value it will limit the upload size, this value should in practice be the larger value by just a little
	How can I make a network share for scans
		All raw scans are saved to scans/file/
		You can create a READ ONLY share
		It can be relocated using /etc/fstab and the bind option like so:
			/path/to/share     /path/to/scans/file           bind    defaults,bind   0       0
	Can I archive old scans
		There is a line commented out in cleaner.php that will give you this feature.
	The upload pritner has a very small file size limit, why?
		PHP has a config.ini file, located at /etc/php/PHP_VERSION_NUMBER/apache2/php.ini
		It has 2 setting relavent upload_max_filesize and post_max_size
		upload_max_filesize is the what limits it, however it has a max value set by post_max_size
Internal Configuration Options:
	Free Space Warning
		This puts a warning on the page if you are low on disk space
		low is defined on line 2 of config.ini
	Fortunes
		This setting is on line 3 of config.ini
		This setting is ignored if the program fortune is not installed
		If it is not working and fortune is installed you may need to update line 201 of index.php with the correct path
	Extra Scanners
		This is a developer tool used for simulating scanners
		This is just for testing the search for scanners feature
		This is set on line 4 of config.ini
	Check For Updates
		Every 24 hours the scanner will check for updates, This is checked on page load
		It only checks the Internet if the last check was over 24 hours ago
		This is set on line 5 of config.ini
	Enable Login
		There are 2 ways, one is pretty and one is not, but the not so pretty one is by far more secure
		Look under apache tricks for the secure one
		The pretty one is enabled on line 6 of config.ini
	Session Duration
		This defines the maximum duration a user stays logged in
		This is set on line 7 of config.ini
	Default Theme
		The default theme is set on line 8 of config.ini, you can get the theme code on the 'Configure' page
		by clicking the 'Save' button under 'Color Scheme'
	Dark Picker
		Tells the page whether or not to use the dark color picker theme by default
		This is set on line 9 of config.ini
	Ruler Increment
		This tells the ruler what measurement system to use 
		This is set on line 10 of config.ini
	Time Zone
		This overrides the system time zone that is set in php.ini as well as auto detect
		This may not be of use for PHP versions older than 5.1
		This is set on line 11 of config.ini
	Printer
		This option enables the server side printing service, the printer must be configured in cups
		This allows one to easily bypass all the crap involved with sharing printers and all the cross-platform nightmares involved!
		Setting this option to 0 disables this feature
		Setting this option to 1 enables it ONLY for printing documents made with the scanner software
		Setting this option to 2 enables it ONLY for uploaded content via the Printer page
		Setting this option to 3 enables it for both uploading documents and printing scanned documents
		This is set on line 12 of config.ini
	ReplacePrinter
		This allows you to disable the client side printing button in favor of the intigrrated one
		This option is ignored if the integrated printer is disabled
		This is set on line 13 of config.ini
	BusterPrintBug
		Debian Buster has a issue with printing PDF files under some conditions
		Setting this option to 0 leaves mitigations disabled
		Setting this option to 1 converts the PDF to a ps file before printing using the pdf2ps command, this may reduce quality, but is faster than 2
		Setting this option to 2-72 reformats the PDF using the convert command with 72 DPI (pdf -> pdf)
		Setting this option above 72 will use that number for the DPI setting, high values may hit a the php ram limit or ImageMagick's max dimensions 
		This is set on line 14 of config.ini
	HomePage
		This option allows one to change the home page within the scanner server
		While is supports a vast number of pages, the only options I consider useful are Scan and Printer
		This is set on line 15 of config.ini
	ShowRawFormat
		This option allows one to show or hide the scanner option to change the raw scan format (pnm or tiff)
		By default this option is hidden for the sake of simplicity
		This is set on line 16 of config.ini
	RawScanFormat
		This option allows one to change the default raw format regardless of the ShowRawFormat setting
		There is no real reason to pick one over the other, unless you one or the other does not work
			See Issue #23: https://github.com/GM-Script-Writer-62850/PHP-Scanner-Server/issues/23
		Setting this option to 0 makes the default format pnm
		Setting this option to 1 makes the default format tiff
		This is set on line 17 of config.ini

Credit where credit is due:
	PHiLLIP KLiEWER
		Original CGI script
	pqwoerituytrueiwoq (at) ubuntuforums.org AKA GM-Script-Writer-62850 (at) github.com
		Conversion/upgrade/security/fixes/cleanup/upgrades
	jhansonxi (at) ubuntuforums.org
		Original CGI cleanup prior to conversion and scanner-access-enabler-*.tar.bz2
	Everaldo Coelho
		Icons (Crystal Clear set)
	ajaxload.info
		Loading bar animation
	odyniec (at) odyniec.net
		imgAreaSelect 0.9.10
	Andy Prevost, Marcus Bointon, and Jim Jagielski
		phpmailer 5.2.6
	openiconlibrary.sourceforge.net
		Powered by Linux image
	Stefan Petre
		ColorPicker (www.eyecon.ro/colorpicker/)
			Does not get full credit, it had lots of issues
	jamesfu
		Proof reading (see issue #18)
	There are a few others, there are comments in the source code for them

Installation Notes:
	Extract files to /var/www/html (or wherever your web pages are visible from)
		Given you already have php installed you can go to http://127.0.0.1 and it will tell you forgot to do as you try to use it
	Install the dependencies (you may use curl instead of php5-cli if you do not want auto delete you do not need either)
		sudo apt-get install tar apache2 php php-cli imagemagick sane-utils php-fpdf
	Add www-data to the lp group
		sudo adduser www-data lp
	Restart service to apply the above command
		sudo service apache2 restart
	Be sure to update imagemagick on Lucid Lynx (Ubuntu 10.04) and CentOS 
	If you cloned the git repo you will need to create some folders, git does not allow empty folders
		sudo mkdir -p /var/www/html/scans/{file,thumb}
		sudo mkdir -p /var/www/html/config/parallel
	Make sure www-data can write files to the scans, config, and parallel folders
		sudo chown www-data /var/www/html/scans/{file,thumb}
		sudo chown -R www-data /var/www/html/config
	You may chmod them to 666 if you prefer
	These command will give you your scanner's URL as a IP address (127.0.0.1 only works on the current system)
		ifconfig | sed -n 's/.*inet addr:\([0-9.]\+\)\s.*/http\:\/\/\1/p'
		ifconfig | sed -n 's/.*inet \([0-9.]\+\)\s.*/http\:\/\/\1/p'
		ip address show | grep 'inet ' | cut -f1 -d'/'| sed  's/inet /http:\/\//'
	This command will give you a easy to remember URL for the scanner (I remember this not working on Windows XP clients)
		echo http://$(uname -n).local/
	Be sure to check http://www.canyouseeme.org/ so you know if people can use your scanner on the Internet, I suggest using a firewall to prevent this, or putting a password on it.
	I recommended enabling .htaccess
		See next section, this will enable faster data transfer over the network, fancy error pages, fancy Index Of pages, cache control, and proper content types
	If you don't have a /etc/apache2/mods-enabled/headers.load file run this command, this enables catch control and defines mime types via .htaccess
		sudo ln -s ../mods-available/headers.load /etc/apache2/mods-enabled/ && sudo service apache2 restart

Apache Tricks:
	Note
		This part was written for a older version of apache2
		These 2 lines:
			Order allow,deny
			allow from all
		Have been replaced with this line:
			Require all granted
		In the current version
	Enabling .htaccess
		open /etc/apache2/sites-available/default
		locate this:
			<Directory /var/www/>
				Options Indexes FollowSymLinks MultiViews
				AllowOverride None
				Order allow,deny
				allow from all
			</Directory>
		you will see "AllowOverride None" change "None" to "All"
		make the change and save it
		now reload apache 
			sudo service apache2 reload

	Password protecting your scanner
		using .htaccess
			be sure .htaccess is enabled (see above)
			make a file called .htaccess in a folder visible over the network
			put this in it
				AuthName "Restricted Area" 
				AuthType Basic 
				AuthUserFile /var/www/.htpasswd 
				AuthGroupFile /dev/null
				Require valid-user
			now me need to make a login (Bob is the user name)
				sudo htpasswd -c /var/www/.htpasswd Bob
			now you will have to login to access /var/www

		using /etc/apache2/sites-available/default
			open /etc/apache2/sites-available/default
			locate this:
				<Directory /var/www/>
					Options Indexes FollowSymLinks MultiViews
					AllowOverride None
					Order allow,deny
					allow from all
				</Directory>
			make it look something like this:
				<Directory /var/www>
					Options Indexes FollowSymLinks MultiViews
					AllowOverride None
					Order allow,deny
					allow from all
					AuthName "Please Login"
					AuthType Basic
					AuthUserFile /etc/apache2/users
					AuthGroupFile /dev/null
					require valid-user
				</Directory>
			now you need to make a login with this command
				sudo htpasswd -c /etc/apache2/users Bob
			now you need to reload apache
			        sudo service apache2 reload
			
	Setting a server name
		Open /etc/apache2/sites-available/default
		Add a new line at the top of the file
		add something like this
			ServerName www.scanner.com
		www.scanner.com and be anything you want
		now run this command
			sudo service apache2 reload
		now apache will not fuss about there not being a server name

	Running apache on a another port
		open /etc/apache2/ports.conf
		notice theses 2 lines
			NameVirtualHost *:80
			Listen 80
		those tell it to use port 80
		you can add more or change them
		for the sake of example we will use port 81 you may use any port number that is not in use (run a port scan to see what is in use)
		so we will add these to lines
			NameVirtualHost *:81
			Listen 81
		now we need to set a path to run on this port
		open /etc/apache2/sites-available/default
		go to the bottom of the file and add this 
			<VirtualHost *:81>
				DocumentRoot /foo/bar # /foo/bar could be /var/www or /home/bob/public_html for example
				<Directory /foo/bar>
					Options FollowSymLinks # follows symbolic links
					AllowOverride All # allows use of .htaccess
					Order allow,deny #allows everyone to access it via browser
					allow from all
				</Directory>
			</VirtualHost>
		now save and run this command
			sudo service apache2 reload