# Copyright (c) 2001 Josha Foust (tivoweb@lightn.org)

Tivo Web - TCL v1.9.4

This is a new branch of the Tivo Web Project - TCL.  It is written entirely in
TCL, is provided under an Open Source license (GPL), runs directly on the TiVo
and provide a lot of the functionality of the original version.  It also (only)
works on 2.0+ software, has the ability to browse the entire channel guide,
perform searches and schedule and delete recordings!  Setup is very simple,
you don't need anything beyond a TCP/IP connection and a shell on your TiVo
(you DON'T need TiVoNet, PPP over serial is fine).

This software should at minimum work on Standalone TiVos on version 2.5.1(a),
3.0, and 2.5.5 for the UK.  It should also mostly work on DirectTiVos with
version 2.5.2.  And it probably still works on 2.0.1.  It will NOT work on
25Xtreme and will not in the future either.

QUICK START INSTALLATION
1. Transfer the archive to your tivo
The best way to get the files to the tivo successfully is to just transfer the
.tar.gz archive via ftp (binary mode), rsync or get it directly onto the tivo
with this command (from a tivo shell): 'http_get -T 0 -C 0 -D /var/hack -U 
http://199.240.141.102:80/tivoweb-tcl-1.9.4.tar.gz'.

2. Move the archive to the appropriate directory
Put the archive in the directory where you want tivoweb-tcl, ie if you want
all the files in '/var/hack/tivoweb-tcl' put the archive in '/var/hack' and it
will unpack into the 'tivoweb-tcl' directory.

3. Unpack the archive
If you have an older version of tivoweb, you should make sure it is shutdown
first, then delete it with 'rm -rf tivoweb-tcl' or move it somewhere else.
Then decompress with 'gzip -d tivoweb-tcl-1.9.4.tar.gz' and unpack with
'cpio -H tar -i < tivoweb-tcl-1.9.4.tar'.  Do not use winzip.

4. Startup
Run "/var/hack/tivoweb-tcl/tivoweb console".  There will be a few messages,
and it will need to load some data.  After it prints "Accepting Connections"
it is ready to go.  Just point your browser at the tivo.  The main tivoweb
stuff is under "User Interface."

OPERATION
For regular operation put "/var/hack/tivoweb-tcl/tivoweb" (with the correct
directory) at the end of the startup script (/etc/rc.d/rc.sysinit).

By default, the images are pulled straight out of MFS.  If you don't like the
look of them or want to crop the borders (which I suggest), save the images
from your browser and modify them in a graphics program.  Then put them in an
'images' directory where you run 'tivoweb' from.  It will check there first
for images, if it doesn't find them, it will go to MFS.  You don't need to
restart tivoweb for this to take effect.  This only works if you save the file
with the same name that is served to the browser.  It won't affect anything
seen from the tivo (like channel logos), just what you see in tivoweb.

If you are waiting a while on the browser to display a web page from
tivoweb-tcl, chances are you are waiting on a 'Lock Conflict' or 'Background
Holdoff'.  If you have the console open where you launched 'tivoweb console'
from, you will be able to see the messages about this.  There isn't anything
you can do but wait for the tivo.

If you get an 'Internal Server Error' on a web page with 'error writing
"file1": I/O error', this is caused by the program trying to write to the
controlling terminal that started it being disconnected.  If you plan to run
tivoweb-tcl without keeping the telnet session open, you should call the
tivoweb startup script without the console arguement, ie just
'/var/hack/tivoweb-tcl/tivoweb'.  But if you get other errors you might want
to see the console output for debugging purposes.

Accessing the web pages shouldn't affect video playback or recording.  During
startup of tivoweb there are sometimes pauses in playback, but shouldn't
affect the recording.

While effort has been made to make the themes look good in a variety of
browsers, the advanced usage of CSS2 really requires Mozilla (Netscape 6).
The technophobe theme will look good in IE 5, but daynight won't.  With the
technophobe theme, some links are hard to distinguish from normal text or
headers.  Specifically the big program name at the top of showing screens
and the 'view upcoming listings' in the channel screen are both useful links.

Another somewhat hidden feature exists that allows sending of multiple keys
in a row via webremote.  By going to http://tivo/sendkey/key1/key2/key3/...
webremote will send those keys in order.  You can enter any valid sendkey keys
plus 'wait' which will pause 3/4 of a second before going to the next key.
This is primarily useful for bookmarking backdoor sequences or interfacing
with other programs.

The multidelete functionality and the descriptions that hover over episode
titles in Now Showing, ToDo and Scheduled Suggestions can add significantly to
the size of those pages, to turn them off edit tivoweb.cfg.

In the 'Restart' menu 'Quick Reload' will reload all of the function
definitions of the modules, but won't run any of the time consuming
initialization functions, 'Full Reload' will.  Both will reload the
tivoweb.cfg configuration file and use the new values.  Quit will shutdown
tivoweb.

SECURITY
It is a very bad idea to make a tivo IP accessable on the internet.  Telnet
has no authentication and a DOS attack can easily crash a tivo.  Even IP-based
access control can be bypassed by simple packet forging.  TivoWeb-TCL does
provides basic authentication services by setting a username and password in
tivoweb.cfg.  If you use this option you should make sure to only allow port
80 through to the tivo from known IPs at the router/firewall level.  That is
probably sufficient protection for tivoweb.  However a much better option is
to use apache (or IIS) as an authenticating proxy to your tivo.  Below are
instructions on how to set that up.  And an SSL authenticating proxy is even
better but can be difficult to setup depending on the OS/distribution used.

PROXY CONFIGURATION
Here is a sample configuration to make your apache server an authenticating
proxy to the tivo.  You will need some understanding of configuring an apache
web server to be able to use this.  This will let you access tivoweb from a
browser by going to http://www.domain.tld:8080/.  Use 'htpasswd
/etc/apache/passwd <username>' to add/edit user's logins.

<VirtualHost *>
ServerName www.domain.tld
...
</VirtualHost>

NameVirtualHost *

Listen 80
Listen 8080

<VirtualHost *:8080>
ServerName www.domain.tld
DocumentRoot /var/www
ServerAdmin webmaster@domain.tld

ProxyPass / http://tivo/
ProxyPassReverse / http://tivo/

<Location />
AllowOverride None
AuthType Basic
AuthName tivo
AuthUserFile /etc/apache/passwd
require valid-user
</Location>
</VirtualHost>

You may also need to uncomment mod_proxy in the load modules section of you
apache configuration file.

If you want to proxy the tivo from a subdirectory of your main site you will
need to change the the following lines in your apache configuration and
tivoweb.cfg file.

Apache config:
ProxyPass /tivo http://tivo/
ProxyPassReverse /tivo http://tivo/
<Location /tivo>

tivoweb.cfg:
Prefix = tivo

BUGS
The way scripting is done, most errors will cause the page to stop loading.
As most pages have tables, it may not display any of the data.  Some of the
pages are designed to print the error messages in the web page, the rest go to
the console.  Of course there shouldn't be any errors, so send me a bug report
about what you were doing at the time and what error message printed.  I will
probably need to have a look at all the objects that the script was
referencing at the time, so sending a dumpobj of those along with the page
source of the web page will help a lot.

DirectTivos are not fully supported.  Currently dual tuner scheduling and
local channels do not work correctly.  Plus a few other small things.

If you don't have guide data, certain parts of tivoweb may not work and may
give errors.  Most of the functionality of tivoweb needs guide data to be
useful anyway.  I do not consider this a bug and thus will not be fixing it.

Daylight savings time calculations is only performed on startup.  So you will
have to restart tivoweb after crossing over a daylight savings time change.

3.0 seems to have a bug in its event handling.  This can cause the TiVo to
lockup after random periods of time.  Tivoweb appears to exacerbate the
problem.  If you experience this problem, try removing the phone module and
doing a complete shutdown/startup of tivoweb, that may help.

Tivosh doesn't like to be killed by control-c or kill while a database handle
is open, it will reboot your tivo.  If you want to stop tivoweb, go to the web
page and shut it down via restart/quit.

Please search http://www.tivocommunity.com/ in the underground section for
questions about how to use or fix a problem you are experiencing with
tivoweb-tcl.  It is the most trafficed site that discusses tivo hacking,
including everything you need to get tivoweb-tcl running.

CREDITS
Stephen Rothwell (sfr@canb.auug.au)
   Original httpd.tcl
Jon Squire (jsquire@justice.loyola.edu)
   SendKeys Tivo Remote Mod
   Namespace separation
   Info screen
Josha Foust (tivoweb@lightn.org)
   Primary author
   Tivo User Interface
   Recording/SeasonPass scheduling and deletion
   Index, image, javascript, form, last-modified and post data support
   Bsearch program and search enhancements
   Logo import code
   Integration of multiple patches
Mike Baker (mbm@linux.com)
   Early and major contributor
   CSS Stylesheets and theme functionality
   Graphical sendkeys remote
   HTML, HTTP, image, post data, file upload and bsearch enhancements
   Testing, debugging and fixing
   Screen module
   Get_space program and original space used algorithm
Mike Byrne (Turbo)
   Resource Editor module
John Paglierani (John@Paglierani.net)
   Program title/description editing routine
Jeff Keegan (jkeegan@keegan.org)
   Mail module
   Log module
   Search module
Dan Stagner (sorphin)
   Resource definition updates for 2.5
Benjamin Tompkins (Juppers)
   Integration of onlive.tcl and added memory info into info module
Luan Dang (luan_dang@yahoo.com)
   Key Trap patch
Mike Langley (mlangley@transedge.com)
   Original multi-sendkey modification to webremote
Philip Edelbrock
   Original patch for basic authentication
Jake B
   Logo module and associated index code
Courtney Bailey
   Phone module
Dale Engle
   Edit Program, Now Showing, Todo, and Series screen enhancements
Dave Boodman
   Original description hover code, multidelete code
Dan Campbell (Angra)
   TmsID index lookup code
Aaron Schrab
   Recording history code
Mike Henry (mrtickle)
   Localization of dates for the UK
