Jump to page content

LIFT Text Transcoder Administrator's Manual

Version 1.7 for RedHat Linux

UsableNet Inc.
528 Canal Street, 2nd floor, New York City NY 10013
Ph: +1 (212) 965 5388
Fax: +1 (212) 965 5391
Email: tt.support@usablenet.com
www.usablenet.com

 

Table of Contents


 

1. Basics


LIFT Text Transcoder (or transcoder) is a web application that converts a web page into its text-only version on-the-fly by eliminating all page layout that is present in the original page and by hiding many accessibility defects.
The transcoder is useful for the website visitor, since it removes some accessibility issues and small defects like missing image ALTs or forms that are not properly linearized or flash objects. It also provides some navigation options that are not usually available on browsers and that enhance the user experience of disabled users or users of mobile technology.
LIFT Text Transcoder can be used also by the web developer to determine if the reading order of the information presented in the page makes sense when read in the order that would be followed by a screen reader or speech browser.

As a webmaster the main advantage of deploying LIFT Text Transcoder is that a "Text mode" link can be added to each page of the website and instantly web visitors can access a text-mode rendering of the content of the pages with no manual work (other than adding the link).

See the User's Manual for additional information on what LIFT Text Transcoder does.

Subsections:

 

1.1. Deploying LIFT Text Transcoder


While LIFT Text Transcoder is very efficient, to transcode a page it has to:

  1. receive a request from the visitor's browser,
  2. issue a request to the webserver hosting the site,
  3. wait for the webserver and the network to yield the data,
  4. transform the page, and finally
  5. send the transformed page to the user's browser.

Figure 1: Interaction between browser, transcoder and web server

Diagram showing the interaction among browser, transcoder and web server

This proxy-like behavior of LIFT Text Transcoder has repercussions on several aspects: performance, security and deployment of LIFT Text Transcoder. Let's start from the last of these aspects.

You can deploy LIFT Text Transcoder in two ways: either LIFT Text Transcoder can be installed on one of your machines within the local network where your web server runs (we call this solution local server) or it runs on machines managed by UsableNet (we call this solution managed service).

Both solutions have their own advantages and disadvantages. The one based on local server has the advantage that LIFT Text Transcoder runs within the same network and physical infrastructure where your web servers are located. And therefore it benefits also from a higher performance, since connections between LIFT Text Transcoder and web servers are very fast.
The solution based on a managed service has the advantage that you don't need to spend time installing and upgrading LIFT Text Transcoder.

Go through this document to learn how the two solutions affect performance and security.

 

1.2. The Administrator's role


For the managed service deployment mode of LIFT Text Transcoder the task of the administrator (who usually is the webmaster) is very simple. S/he has to decide which websites can be processed by LIFT Text Transcoder and to install proper "Text mode" links on pages that the LIFT Text Transcoder has to process.

For the local server solution the task of the administrator comprises more activities. The administrator is expected to:

In both cases the administrator should handle communication between web visitors and UsableNet support staff when it is believed that LIFT Text Transcoder does not work as it is expected to. The administrator should also allow (and perhaps come along with) UsableNet engineers to inspect LIFT Text Transcoder, diagnose a problem and implement a solution. Possibly also in a remote way via a network connection over a ssh terminal session or a telnet connection.

LIFT Text Transcoder comes along with an optional package (Web Admin) that, if installed, offers a web-based interface for the most frequent administrative functions. Point your browser to http://TRANSCODER_SERVER:8080/tt-admin (where TRANSCODER_SERVER is the name of the server that hosts LIFT Text Transcoder) to get access to such a functionality, if available. And read about it in section Web interface for the administrator.

 

2. How to deploy LIFT Text Transcoder managed by UsableNet


When purchasing this solution you need to decide how many web servers the LIFT Text Transcoder has to process (real and virtual servers are alike). If you need to apply LIFT Text Transcoder on pages hosted by www.mycompany.com then coverage of a single server suffices; if you need to use it for pages hosted by www.mycompany.com, www.products.mycompany.com and people.mycompany.com then three servers have to be covered.

Consider that while processing a page LIFT Text Transcoder rewrites the URLs contained in the page so that the actual browser request gets filtered by LIFT Text Transcoder. However this URL remapping occurs only for URLs that are based on servers on which LIFT Text Transcoder is allowed to work. I.e. whose pages LIFT Text Transcoder may transcode. If a URL is not remapped then the visitor browser will display the normal original page.

For this reason when purchasing this solution you need to tell to the UsableNet representative how many servers have to be covered by LIFT Text Transcoder and their names as well. Should you need to change the name of some server please contact UsableNet's staff (tt.support@usablenet.com).

The second step is to install text mode links within your pages. See the How to set up text-mode links section.

 

3. How to set up text-mode links


Subsections:

 

3.1. Adding text-mode links to pages


This is an easy step. To allow LIFT Text Transcoder to generate on the fly these text-only pages you only need to create a new link on your pages and have that link point to the LIFT Text Transcoder. It will work on static pages, dynamic pages (e.g. asp, jsp), on pages produced by a Content Management System or pages pulled out of a database; on pages with any sort of web content and even forms.
Visitors of your website will be able to follow such text-mode links, and then be able to navigate through your website (within the web server names limits described in sections How to deploy LIFT Text Transcoder and Installing the serial number) in text-mode. They will be able at any time to switch back to your real web pages (i.e. without using LIFT Text Transcoder at all).

The text-mode link should look like in this example: 

<a
href="http://transcoder.usablenet.com/tt/http://www.mycompany.com/some/page.html" 
title="text-only page produced automatically by LIFT Text Transcoder">Text only</a>

where http://www.mycompany.com/some/page.html is the URL of the page containing the text-mode link (i.e. the one that you are editing) and transcoder.usablenet.com is the server name where LIFT Text Transcoder is running.

If you need to code a text-mode link for a page that should be handed to the browser via an HTTPS connection then you only need to change both occurrences of HTTP with HTTPS, i.e. 

<a
href="https://transcoder.usablenet.com/tt/https://www.mycompany.com/some/page.html" 
title="text-only page produced automatically by LIFT Text Transcoder">Text only</a>

If you decide to put the "text-mode" link in more than one page, and having to specify each time the actual URL of the page to be transcoded is a hassle (like when you use templates for the page heading that are shared among a large number of pages) then you can adopt the following mechanism.

The "text-mode" link should look like this example: 

<a
href="http://transcoder.usablenet.com/tt/referrer" 
title="text-only page produced automatically by LIFT Text Transcoder">Text only</a>

LIFT Text Transcoder will use the Referer request-header field (as defined by the HTTP protocol) to get the URL to process.

The two mechanisms are quite equivalent; the difference is that "text-mode" links based on the latter (the one using the "referer" HTTP header) will not work if the user's browser does not process such a heading. This can happen if the user has disabled such a heading or for browsers that do not support it (for example some browsers on PDAs do not process it).
Notice that the HTTP protocol field name is "referer" whereas the URL we require to use ends with "referrer" with a double "r".

To speed-up even more the interaction with the user's browser, LIFT Text Transcoder does an automatic HTTP content compression of the data. This is an activity that is totally transparent to the user of the browser and the LIFT Text Transcoder administrator.
Performances described in the benchmark do not take advantage of this compression mechanism. With the current version of LIFT Text Transcoder the performance figures in general improve.

In addition to adding such a visible text only link (for the benefit of those that can see it when visually scanning the page), consider adding also a hidden text only link at the very beginning of the page. In this way web visitors using screen readers or small devices (PDAs, smart phones) not supporting images can get it early, before they have to sift it out from all the content of the page.

One simple way for achieving this is to add a hidden link based on a spacer image, as follows: 

 <a
 href="http://transcoder.usablenet.com/tt/http://www.mycompany.com/some/page.html"
 ><img src="images/spacer.gif"
 style="border:none"
 alt="text-only page produced automatically by LIFT Text Transcoder"
 width="0" height="0"/>
 </a>
 

3.2. Bookmarklet to use in your visitor's browsers


To further enhance the ability for your visitors to use the LIFT Text Transcoder that you deployed in your site, you can place in some introductory page a bookmarklet that can be added to their browsers. Whenever they visit a page and select/click such a bookmark, LIFT Text Transcoder is activated on the visited page (if the page is within the realm of pages that can be processed by LIFT Text Transcoder).

The following link can be bookmarked (i.e. put in your favorite links). Once it is there, and you browse any web page on which LIFT Text Transcoder can be applied to, if you click such a bookmark the browser will display the text-only page generated by LIFT Text Transcoder. Actually the bookmark works as a toggle button: click it once to view the text-only page, click it again and the browser will display the original page.

Text-only toggle

This link is implemented as follows: 

<a href="javascript:if
 (window.location.href.indexOf('http://transcoder.usablenet.com/tt/')==0)
 window.location = window.location.href.substring(35,
 window.location.href.length); else
 window.location='http://transcoder.usablenet.com/tt/' +
 window.location;">Text-only toggle</a>

This bookmarklet works only on Javascript enabled browsers. And only if you have access to LIFT Text Transcoder. You might need to manually edit the code of the bookmarklet to change the server name that hosts LIFT Text Transcoder. Editing a bookmarklet is easy: simply save it as a link within an HTML page, edit its Javascript code and then bookmark the link again. What you need to do is to replace the occurrences of "transcoder.usablenet.com" with the server name on which LIFT Text Transcoder is running within your organization. 35 is the number of characters included in "http://transcoder.usablenet.com/tt".

Each bookmarklet (aka favelet) is a tiny program (a Javascript application) contained in a bookmark (the URL uses a "javascript:" protocol) which can be saved and used the same way you use normal bookmarks. Learn more about bookmarklets ...
This bookmarklet is easy to install, poses no security threats to your machine or browser, and is free.

 

4. How to install LIFT Text Transcoder locally


Subsections:

 

4.1. System requirements


The hardware used to run LIFT Text Transcoder should meet at least the following requirements:

LIFT Text Transcoder is based on the following underlying (open source) products:

These components are used in their original version and integrated within the LIFT Text Transcoder software architecture.
To install LIFT Text Transcoder you need to have a Red Hat machine with the proper Tomcat and Java packages already installed and configured.

 

4.2. Installing or upgrading the LIFT Text Transcoder software


LIFT Text Transcoder is available as an RPM package. To install LIFT Text Transcoder you need to log in as root and perform the following command: 

rpm -ivh lift-text-transcoder-X.X-X.i386.rpm

At the end of installation process, the rpm command will perform the following setup:

  1. update Tomcat configuration by changing the file /var/tomcat4/conf/tomcat4.conf. The original file will be saved as /var/tomcat4/conf/tomcat4.conf.orig
  2. restart of the Tomcat service with the following command: 
    service tomcat4 restart

To make sure that LIFT Text Transcoder is running properly try to use it and then inspect the log files. You must complete the installation first, by following all the relevant steps specified in this section. Then, to make sure it runs properly, point your browser to a URL like http://TRANSCODER_SERVER:8080/tt (where TRANSCODER_SERVER is the server name of the machine where LIFT Text Transcoder has been installed) and see that the appropriate page can be seen. Try exploring the online documentation and finally type a URL to be transcoded in the appropriate field. Then look at the log files to see if there are any warning messages. See also section 7.1 on log files.

We are planning a number of new releases of LIFT Text Transcoder with new functionalities and improvements. Visit the release notes page to make sure that you run the most recent version of LIFT Text Transcoder.

Upgrading LIFT Text Transcoder is easy. All you need to do is to login as root and to:

  1. make sure nobody is using LIFT Text Transcoder and stop the Tomcat service with 
    service tomcat4 stop
  2. execute the rpm update command: 
    rpm -Uvh lift-text-transcoder-X.X-X.i386.rpm

    This command will install the new version of the software and check that all the components of LIFT Text Transcoder are present. It will also update configuration files (saving the existing ones on a file with the same name but ending with .rpmnew).

  3. start the Tomcat service again: 
    service tomcat4 start
 

4.3. Installing the serial number


LIFT Text Transcoder cannot run without a valid, properly installed serial number.

The LIFT Text Transcoder serial number is delivered as a text file that must be copied in the directory /var/tomcat4/webapps/tt/conf with the name serial-number.txt.

After you copied the file remember to restart the Tomcat service:

As root do: service tomcat4 restart.

Make sure that the serial-number.txt file has a read permission for everyone. Do a chmod a+r serial-number.txt to allow everybody (that has access to the server) to read it.

 

4.4. Defining the text-mode realm


You need to tell LIFT Text Transcoder which are the web servers whose pages it can process. These servers and pages define the "space" (or realm) where web visitor can navigate in text-mode.

Simply edit the file /var/tomcat4/webapps/tt/conf/tt-config.xml and edit or add the section called accepted-hosts as in the following example: 

  <accepted-hosts>
    <host>www.mycompany.com</host>
    <host>news.mycompany.com</host>
  </accepted-hosts>

Unless you purchased an "Unlimited" license, remember to check that the number of accepted hosts does not exceed the number stated in your license file. Should this happen LIFT Text Transcoder will refuse to process any page, regardless the server it is hosted on.

The "Unlimited" license allows to specify entire subdomains to be processed by LIFT Text Transcoder. Subdomains must be written starting with a dot, as the following example: 

  <accepted-hosts>
    <host>.mycompany.com</host>
    <host>.myothercompany.com</host>
  </accepted-hosts>

Remember also that only pages hosted on these servers will be transcoded by LIFT Text Transcoder. If a page hosted by one of these servers contains a link to a page hosted by a server that is not listed, LIFT Text Transcoder will not transcode the latter page.

 

4.5. Network configuration


By default LIFT Text Transcoder needs to be reachable on TCP port 8080. This means that if you use a firewall, that port has to accept incoming requests. In addition, to handle HTTPS connections, LIFT Text Transcoder has to be reachable on TCP port 8443. If you want LIFT Text Transcoder to be reachable on ports 80 and 443 too, please see the Running on default http and https ports section.

LIFT Text Transcoder also needs to reach web servers. By default, it issues (outgoing) requests on TCP ports 80 or 443 (for HTTP and HTTPS requests, respectively).

 

4.6. Running on default http and https ports


If you need LIFT Text Transcoder to be reachable on ports 80 and 443 too, you must be sure that no other web server is running on the same ports. Then you can configure iptables to redirect all requests on port 80 to port 8080, and 443 to 8443. All the commands described here must be run as root user.

First, it is necessary to stop and disable the web server if it is running: 

service httpd stop
chkconfig httpd off

Then define the iptables rules as follow: 

iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
iptables -t nat -A OUTPUT -p tcp --dst servername --dport 80 -j REDIRECT --to-port 8080
iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443
iptables -t nat -A OUTPUT -p tcp --dst servername --dport 443 -j REDIRECT --to-port 8443

Please insert for "servername" the name of the server where LIFT Text Transcoder is running.

Finally, save the iptables configuration, so it can be loaded at system boot. 

iptables-save > /etc/sysconfig/iptables
 

4.7. Installing new root certificates


As described in User's Manual: Security aspects at times LIFT Text Transcoder needs to manage locally-installed certificates in order to establish secure connections.

One possible problem that a LIFT Text Transcoder user may encounter is that the web server it connects to has a Root Certificate that is unknown to LIFT Text Transcoder. In such a case LIFT Text Transcoder produces an HTTPS error page. (A root certificate is a certificate that is issued by some Certification Authority to certify itself; if your web server handles secure connections via public certificates, there is already an appropriate root certificate stored somewhere within the configuration files of the web server.)

Solution of this problem is easy: you need to install such a root certificate on Tomcat, the web application server LIFT Text Transcoder is based upon. Follow these easy steps:

  1. Obtain the root certificate file (either get it from your web server configuration files or download it from the Certification Authority that released it; for example from Verisign.com).
  2. Stop the Tomcat service: 
    service tomcat4 stop
  3. Install it so that Tomcat can see it. From the root account issue the following shell command (in a single line): 
     <java_home>/bin/keytool -keystore <java_home>/jre/lib/security/cacerts
   -import -alias <new_alias> -file <root_cacert_file>
    where java_home is the directory where the Java system used by Tomcat is installed (usually something like /usr/java/j2sdk1.4.2_01); new_alias is the local name you are giving to the certificate (this name can be used to retrieve the certificate; it is not used at all by Tomcat); and root_cacert_file is the file name containing the root certificate itself.
  4. Start the Tomcat service: 
    service tomcat4 start

If you need to see which root certificates are already visible to Tomcat (and hence to LIFT Text Transcoder) you can issue the following command: 

 <java_home>/bin/keytool -keystore <java_home>/jre/lib/security/cacerts -list

Note: when handling root certificates you usually need to enter a password. The default password used by the Java system is "changeit", unless it has been changed by a security-conscious administrator.

 

4.8. Installing public certificates


The previous section describes how to install root certificates, i.e. certificates issued by certification authorities to state that they are an authority. This section explains how to install on LIFT Text Transcoder public certificates, i.e. certificates that you created and installed on your web server to support HTTPS connections. You can locate these certificates within some configuration file of your web server.

NOTE: if your web server does not support HTTPS connections then you don't need to worry about these certificates. LIFT Text Transcoder will not use them either.

Solution of this problem is also easy: you need to install such a public certificate on Tomcat, the web application server LIFT Text Transcoder is based upon. Follow these easy steps (see the tomcat how-to tutorial for additional details):

  1. Stop the Tomcat service: 
    service tomcat4 stop
  2. Create a keystore file by adding a new private certificate issuing the following shell command (in a single line): 
    <java_home>/bin/keytool -genkey -alias tomcat -keyalg RSA 
   -keystore /var/tomcat4/.keystore
    where java_home is the directory where the Java system used by Tomcat is installed (usually something like /usr/java/j2sdk1.4.2_01). This command will create a file .keystore in Tomcat directory.
    (You need to enter a password required by the keytool command: the default password is changeit)
  3. Install the public certificate so that Tomcat can see it. From the root account issue the following shell command (in a single line): 
    <java_home>/bin/keytool -keystore /var/tomcat4/.keystore
   -import -alias <new_alias> -file <cert_file>
    where new_alias is the local name you are giving to the certificate (this name can be used to retrieve the certificate; it is not used at all by Tomcat); and cert_file is the file name containing the certificate itself.
  4. Start the Tomcat service: 
    service tomcat4 start

If you need to see which certificates are already visible to Tomcat (and hence to LIFT Text Transcoder) you can issue the following command: 

<java_home>/bin/keytool -keystore /var/tomcat4/.keystore -list

Note: when handling root certificates you usually need to enter a password. The default password used by the Java system is "changeit", unless it has been changed by a security-conscious administrator.

 

5. Performance aspects of LIFT Text Transcoder


Consider again the diagram shown at the beginning of this document.

Figure 2: Interaction between browser, transcoder and web server and between browser and web server

Diagram showing the interaction among browser, transcoder and web server

The response time for getting a text-only page (i.e. the time the web visitor has to wait to see some results), compared to the time to get the original page, is affected by steps 2, 3 and 4.
Depending on whether the transcoder is installed in the same local network as the webserver or in a different network, the performance will differ (the latter case is the worst as steps 2 and 3 require more time).

We carried out a benchmark for determining the performance of LIFT Text Transcoder and interesting results are available on UsableNet's website.

The conclusion is that the deployment modality of LIFT Text Transcoder is just one of the factors affecting performance. Other factors are:

  1. speed of the connection between browser and web server (arrows 6 and 7)
  2. speed of the connection between browser and LIFT Text Transcoder (arrows 1 and 5)
  3. speed of the connection between LIFT Text Transcoder and web server (arrows 2 and 3)
  4. complexity of the original page (in terms of how much processing LIFT Text Transcoder has to perform in order to hide or change elements)
  5. size of the original page (and therefore amount of data that needs to be transferred in connections 3 and 7, from web server to LIFT Text Transcoder and to browser respectively)
  6. size of the transcoded page (and therefore amount of data that needs to be transferred in connection 5, from LIFT Text Transcoder to the browser).

A local server deployment of LIFT Text Transcoder increases the speed of connections between LIFT Text Transcoder and web server (arrows 2 and 3). And depending on the other factors, the response time to access a web page through LIFT Text Transcoder (arrows 1, 2, 3 and 5) may actually be significantly less than the response time to access the normal page (arrows 6 and 7), because of the difference in size and rendering complexity between these two pages.

 

6. Security aspects of LIFT Text Transcoder


See the discussion of public and private HTTPS certificates in User's Manual: Security aspects.

LIFT Text Transcoder supports multipart/form-data content type when submitting a form. This means that users can upload files using forms.
You can easily disable this feature by editing the file web.xml located in /var/tomcat4/webapps/tt/WEB-INF.
Set the parameter enable-uploads to false to disable file uploads or set the parameter upload-max-size to limit the size of uploaded files. Current max size is set to 500 Kbytes.

 

7. Day to day management of LIFT Text Transcoder


Subsections:

 

7.1. Enabling log files


If you need to monitor LIFT Text Transcoder activity, its log files are an important resource. From them you can determine the amount of traffic that goes through your LIFT Text Transcoder, demographic data about your visitors, and potential problems with your installation of LIFT Text Transcoder.

You can easily configure Tomcat to log all the accesses to LIFT Text Transcoder and all its error messages. All you need is to add the following XML fragment to the file server.xml located in /var/tomcat4/conf.

The fragment must be placed inside the <Host> tag that handles the transcoder service (Tomcat can handle one or more virtual servers: the Host tag allows you to define them). Usually you can put the fragment inside the "localhost" <Host> element, i.e. the default host handled by Tomcat. But in other cases you might want to define another hostname for the LIFT Text Transcoder service.
See Tomcat's Server Configuration Reference for more information about configuring server.xml, handling virtual hosts and customizing the log files.

This is the fragment for enabling logs that needs to be included within the Host tag: 

<Context path="/tt" docBase="tt" debug="0" 
         reloadable="false" crossContext="false">
    
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         directory="logs" prefix="tt_access." suffix=".log"
         pattern="combined" resolveHosts="false"/>

  <Logger className="org.apache.catalina.logger.FileLogger"
          directory="logs"  prefix="tt." suffix=".log"
          timestamp="true"/>

</Context>
 

7.2. Managing log files


If logs are enabled (see previous section) all LIFT Text Transcoder activity is logged on files under the directory /var/tomcat4/logs:

The log file startup.log is located in /var/tomcat4/webapps/tt/WEB-INF/logs. It contains data about the initialization of LIFT Text Transcoder showing license data, administration data, the list of accepted hosts to transcode and the number of hosts that can be still added to this list.
Use this file to make sure that the appropriate parameters and values have been correctly read by LIFT Text Transcoder.
The startup.log file is generated the first time LIFT Text Transcoder processes a page request after Tomcat has been restarted. Therefore, if you need to check the content of the log file after a Tomcat restart, point your browser to the LIFT Text Transcoder Main Page (i.e. /tt/index.html). After the page has been delivered to your browser inspect the startup.log file.

Old log files are automatically compressed and the oldest ones are automatically removed.

For Managed LIFT Text Transcoder users: upon request UsableNet staff will be happy to send you, at the beginning of each month, the log records for the web servers that you registered. This is a service already included in the subscription fee. Just send an email to tt.support@usablenet.com.

 

7.3. Monitoring LIFT Text Transcoder


LIFT Text Transcoder is a reliable application, if properly configured and managed. It means that it will keep working for long periods of time without requiring any attention.

However we suggest that you periodically monitor its behavior. In particular you should watch its response time (how long has a web visitor using your LIFT Text Transcoder to wait before getting the transcoded page) and if, for some reason, it might not be working any more.

To watch response times you can try it by hand or you can adopt a more systematic approach (using tools like JMeter) to set-up automatic measuring of response times. If you discover that response time of LIFT Text Transcoder hits too high limits there are several options you can adopt to resolve the issue, ranging from fine-tuning LIFT Text Transcoder to adding additional hardware. Please get in touch with tt.support@usablenet.com and we will be glad to help you solve the problem.

Should LIFT Text Transcoder crash for some reason, it will automatically try to restart in less than 5 minutes (actually a crontab based mechanism periodically checks if Tomcat is still running; if not it will restart it automatically). Therefore no specific action on your side is required.

The most probable reason for crashing is due to improper configuration of LIFT Text Transcoder: see next section.

 

7.4. Fine tuning LIFT Text Transcoder


Depending on how frequently LIFT Text Transcoder is being used, how many simultaneous users are there, the characteristics of the pages to be transcoded, and the performance of underlying machine where LIFT Text Transcoder is running, appropriate configuration might be needed to improve throughput, response time and reliability.

By large, the most frequent problem is due to insufficient memory being allocated to Tomcat, the web application server used by LIFT Text Transcoder.

Depending on how much RAM and swap space is available on your machine, configure appropriately the following parameters. We suggest that you allocate at least 256 MByte to Tomcat and that you start the Java Virtual Machine used by Tomcat in server mode.

Edit the file /var/tomcat4/conf/tomcat4.conf and make sure that the option called JAVA_OPTS is set as follows 

JAVA_OPTS="-server -Xmx256m"

that specifies to start the JVM in server mode and with a memory footprint of 256 Mbytes. If your machine has 1 GByte of RAM, then consider allocating to Tomcat 512 MByte or more.

If you would like to implement more specific tuning, please send an email at tt.support@usablenet.com. We'll be glad to assist you.

 

8. Customizing LIFT Text Transcoder


Subsections:

 

8.1. Server names


LIFT Text Transcoder needs to know the name of the server it runs on (for example transcoder.usablenet.com). This is needed when LIFT Text Transcoder rewrites the URLs that it finds on pages that it processes. By default it will rewrite these URLs without adding any server name nor port number (in which case the server name and port number specified in the HTTP/HTTPS request will be sent to LIFT Text Transcoder by the browser). But if you want to specify a server name and possibly a port number (other than the default ones: 8080 for HTTP and 8443 for HTTPS), then edit both the parameters called http-server and https-server. We suggest that you define both these parameters or none of them.

Edit the LIFT Text Transcoder configuration file /var/tomcat4/webapps/tt/conf/tt-config.xml and edit the sections called http-server and https-server as follows: 

 <http-server>YOUR_SERVER_NAME:YOUR_PORT</http-server>

and similarly for HTTPS-SERVER.

If you set a port number different than the default one, make sure that the system is configured so that tomcat is actually listening to the port that you defined.

 

8.2. Setting speedbumps


Among other things you can customize LIFT Text Transcoder so that when a web visitor navigating in text-mode hits the border of the text-mode realm (i.e. follows a link that goes outside the text-mode realm; - see section Defining the text-mode realm) the most appropriate behavior is performed.

You can configure LIFT Text Transcoder to behave in two different ways: either the web visitor, after clicking such an outgoing link, reaches the resulting page in graphic-mode (i.e. with no LIFT Text Transcoder processing whatsoever) or the user reaches that page transcoded through the demo LIFT Text Transcoder service managed by UsableNet.

In the former case, switching from a text-mode page to a graphic page is sudden, and the web visitor might not be aware that s/he has hit a border. This might lead to some confusion on his/her side.

In the latter case, LIFT Text Transcoder will display a speed-bump page alerting the user and telling him/her that the border has been hit and that there are two options: either continue in text-mode by using the demo service, or switch to graphic mode.
The web visitor has also the option to set, in an appropriate LIFT Text Transcoder preference, whether to hide or show these speed-bumps. So we suggest that by default you enable speed-bumps.

To enable speed-bumps you need to edit the file /var/tomcat4/webapps/tt/conf/tt-config.xml and edit the section called speedbumps as follows: 

 <speedbumps>yes</speedbumps>

To disable them use "no" instead of "yes".

 

8.3. Email addresses


LIFT Text Transcoder offers in many of its pages the email address of the administrator, so that LIFT Text Transcoder users can easily get in contact if help or clarification is needed. For this reason LIFT Text Transcoder needs to "know" to the email address of the administrator.

Open with a text-editor the file /var/tomcat4/webapps/tt/conf/tt-config.xml and edit the section called admin-email by setting the proper email address.

LIFT Text Transcoder, if it encounters some weird situation, sends a warning to the administrator via email. To do so it needs to "know" which SMTP server to use (to deliver email) and what kind of "From" address to use when composing the message.

Open the /var/tomcat4/webapps/tt/conf/tt-config.xml file and edit the sections called mail-host (by default the SMTP server is localhost) and mail-sender.

 

8.4. Admin username and password


To be able to use the Web Admin extension of LIFT Text Transcoder you need to set up a username and password to use as credentials when logging in as administrator. These credentials will be automatically set up (username=admin, password=password) when Web Admin is installed (see section Installation of Web Admin).

To manually change these credentials (rather than changing them through the Web Admin interface) open the file /var/tomcat4/webapps/tt/conf/tt-config.xml and edit the sections admin-username and admin-password. Any sequence of printing characters is valid. Avoid using the "&" symbol.

 

8.5. Annotations


LIFT Text Transcoder can be customized, on a website basis, so that it can produce pages that are even more useful than those that are produced by the default behavior of LIFT Text Transcoder.

The kinds of customizations that can be implemented so far (but the list is being extended by UsableNet's engineers each day) concern addition or removal of elements included in pages, or the way in which elements can be rendered. The following list gives you an idea of a sample of what can be achieved:

Such a customization can overcome some of the limits of LIFT Text Transcoder, namely its inability to handle Javascript code that is used within a page, especially code for validating and submitting form values. (This problem is not due to technological limits of LIFT Text Transcoder, but rather it reflects a fundamental limit for any conceivable computerized processing of Javascript code.)

Customization of LIFT Text Transcoder is based on annotations, XML files that contain references to existing web pages and that supply additional information that is used by LIFT Text Transcoder when transcoding the page. Via annotations you, as a webmaster, can easily add more power to the transcoder and specify how features of your website (for example forms) should be transcoded into true accessible pages. The power of annotations is that you don't need to change anything in the original web pages. LIFT Text Transcoder will merge the original page and the annotations that refer to it and produce the resulting text-only accessible page.

If you'd like to customize the behavior of LIFT Text Transcoder please get in contact with tt.support@usablenet.com. Depending on the kind of customization you need, you might be required to produce some prototype example of web pages demonstrating it.

 

8.6. Marking HTML fragments for removal


One common requirement is to have LIFT Text Transcoder drop some part of the HTML page (for example unwanted text-only links, or poor ALTs). You can achieve this also without having to write a specific annotation, but by using a special (but valid) markup on your HTML code.

There is an easy way to identify the HTML fragments that LIFT Text Transcoder should remove while processing a web page.
You simply have to embed those fragments inside a DIV element with the attribute class set to un_jtt_hide. The following is an example: 

<p>Introduction ...</p>
<div class="un_jtt_hide">
  <p>Offending code</p>
</div>
<p>Conclusion ...</p>

Will be transcoded into:

<p>Introduction ...</p>
<p>Conclusion ...</p>

If the HTML fragment contains only inline elements instead of block-level elements, you can use the SPAN element to mark the fragment to remove: 

<a href="index.html">Home page</a>
<span class="un_jtt_hide"><a href="javascript:...">Javascript based link</a></span>
<a href="products.html">Products</a>

In general LIFT Text Transcoder will remove all the elements in your page that have class="un_jtt_hide".

 

9. Web-based interface for the administrator


If the optional package Web Admin is installed, the URL http://TRANSCODER_SERVER:8080/tt-admin (where TRANSCODER_SERVER is the name of the server that hosts LIFT Text Transcoder) supports a web-based interface to the most frequently used administrative functions of LIFT Text Transcoder. We suggest you use this functionality if you feel insecure about editing configuration files for Tomcat and LIFT Text Transcoder.

On the other hand consider that everybody in the world can access that URL (which is not secret) once the Web Admin package is installed. A minimum level of security requires that you

  1. choose a secure password for the admin account (i.e. a password with more than 8 characters, some digits and punctuation marks)
  2. remember to change frequently the password
  3. monitor (by looking at the webserver logs produced by LIFT Text Transcoder) who and when tries to connect to that URL.

Subsections:

 

9.1. Installation of Web Admin


Web Admin is available as a package and requires LIFT Text Transcoder to be already installed.

To install Web Admin you need to issue, as root, the following command: 

rpm -ivh lift-text-transcoder-admin-X.X-X.i386.rpm

At the end of the installation process point your browser to the URL http://TRANSCODER_SERVER:8080/tt-admin and do a login using as username "admin" and as password "password". IMPORTANT: Activate the "Account" button and change your password. If you don't do this, everybody will able to get the default password (from the online version of this manual) and login into your installation of LIFT Text Transcoder as administrator, seriously compromising the security of LIFT Text Transcoder.

 

9.2. Logging in and out


Use the login form available at http://TRANSCODER_SERVER:8080/tt-admin (where TRANSCODER_SERVER is the name of the server that hosts LIFT Text Transcoder) and the account named "admin" with the password that you selected during the installation process to get access.

Although LIFT Text Transcoder will automatically log you out if it detects no activity within a period of time, we suggest that you activate the "Logout" button every time you are done with the administrative functions.

 

9.3. Editing the text-only realm


Activate the "Servers" button to get into a window that allows you to add, change, remove or edit the names of the servers. Activate the "Save" button to save the list in the appropriate configuration file. The "Unlimited" license allows to specify entire subdomains to be processed by LIFT Text Transcoder. Subdomains must be written starting with a dot (example: ".nasa.gov", ".w3c.org").

If you want to make sure that all the servers that you entered are responding (on port 80, the default port used by webservers) then activate the button "Test & Save". LIFT Text Transcoder will issue an HTTP GET request to each of the listed servers to make sure that their name has been typed correctly and will list the servers that are not responding (probably because of a mistyped name). In any case the list will be saved on the configuration file. Subdomains, supported by "Unlimited" license, are not tested.

Use the "Save" button to avoid the time-consuming test on server names and to add servers that do not exist yet. Use the "Test & Save" button to let LIFT Text Transcoder warn you if you made some typing error. Remember that regardless of the outcome of the test, the list will be saved.

LIFT Text Transcoder will read the data from the configuration file just when you select the Servers button, and will save the data in the configuration file when you press the Save or Test & Save buttons. In this way, if you want, you can also edit manually some of the configuration parameters (i.e. by editing the files in which the parameters are stored). Be careful to avoid an accidental overwriting of data.

The functionality provided by the Servers window implements the changes described in section Defining the text-mode realm.

 

9.4. Editing other options


The Options window allows you to change in part the behavior of LIFT Text Transcoder. In particular:

 

9.5. Editing account preferences


The Admin account window allows you to change the username and password used by the administrator of LIFT Text Transcoder when using the web-based user interface (i.e. Web Admin).

For security reasons we strongly suggest you to change such an information as a first thing after installing Web Admin.

See section Admin username and password.

 

9.6. Uninstalling Web Admin


Uninstalling Web Admin is easy. (If you are concerned about the security of your LIFT Text Transcoder installation and don't need a web-based interface to manage it, this is a sound solution.)

Simply issue the following command (as root user): 

rpm -e lift-text-transcoder-admin
 

10. Quick reference guide


As a quick reference these are the configuration and log files used or written by LIFT Text Transcoder and by Tomcat. Frequently used commands are also listed.

Website Testing Systems
© 2004 UsableNet Inc. All rights reserved.