Clearlight Communications User's Guide
Rev 30-Aug-2001
Please Note:
References in this guide to "www3.clearlight.com" may be different if your account resides on a different server. Please substitute "www", "www1", "www2", etc. for the server where your account lives.
Hostname references to "<hostname>.clearlight.com" mean that you should substitute the host name of your server (hpserv, bardo, deva, etc.) for <hostname>. An example host name is "deva.clearlight.com".
Level 2 or Level 3 account users may use their domain name as a host name. For example, "youdomain.com" or "www.yourdomain.com" should be substiuted for host name references to your web site.
FrontPage users should refer to sections 1 & 26.
It's important that each account be protected by a strong password. Even on secure systems, an account password is considered the weak link. There are several ways that an individual account password on a public system can be guessed or cracked. It's common for a password to be guessed by trial and error using a dictionary list of commonly used password combinations. A strong password has at least six characters and is not related to your user name or company name.
If your account user name is the primary login for your web site, then the associated password provides access for email, telnet, and ftp. Just login to your account via SSH or Telnet and type "passwd". If you are a FrontPage user, your Unix account password should be different from the one used for FrontPage access.
If you are not using FrontPage, then you will transfer files from your computer to our server by using FTP (File Transfer Protocol). FTP uploads are most easily performed through the use of a dedicated FTP software program. If you don't yet have a dedicated FTP software program for your computer, here are some popular packages that are publicly available:
For Macintosh users, we recommend Fetch
For Windows users, two popular choices are:
WS_FTP Light
CuteFTP
WS_FTP Pro is our favorite commercial FTP program. Evaluation copies are available from Ipswitch.
To configure your FTP software, set the 'host type' for "Unix- standard" or a similar setting. Use lowercase letters for your login name, and remember that your username and password are case- sensitive. After connecting, you will automatically be pointing to your home directory (/users/<username>). Your web documents will need to be transferred into a directory that is contained within your home directory named "web". See below for details.
As an example, here is a session configuration for WS_FTP:
Host Name: <yourdomain>
Host Type: Unix Standard
User ID: (your account username)
Password: (your account password)
Account: (leave blank)
Initial Directories
Remote Host: (leave blank) Automatically set for your home directory.
Local PC: This is for your convenience. Set it to the hard disk
location where the web files to be transferred are located (for
example "c:\homepage"). If you save your session, WS_FTP will point
there the next time you use it.
A dedicated FTP software package is the easiest way to upload and manage files on the server. It is required in order to upload sensitive text files such as CGI scripts and email control files. However, it is possible to use your web browser to upload HTML and graphics files if you are using a recent web browser.
If using Netscape version 2.0 or greater, enter this URL (substitute "username" with your username, and "your.domain" with your own domain name):
ftp://username@your.domain/users/usernameYou will be asked for your password, and then will see an index of your home directory. Remember to select the folder named "web" as the destination for your web site files. Under the "File" menu, you will now see the item "Upload File" available to you.
Microsoft Internet Explorer 5.x can also be used to upload standard web files using FTP. Explorer uses a FTP URL similar to:
ftp://username@your.domainAgain, be sure to select the folder named "web" as the destination for your web site files.
After updating files in your "web" folder via FTP, it is important to press "reload" in your browser in order to see the changes. Otherwise, you will likely be viewing the old version of the document from the web browser's cache.
All of the files that you want to be accessible on the web server must be located in the directory named "web" in your home directory. Your home directory is already set up with a "web" directory and a default home page named "index.htm". This is the page that will be loaded by default when someone uses your URL (our default page displays an animated "Under Construction" graphic). Replace the existing "index.htm" with your own and you're in business!
If you use the filename "index.html" or "index.htm" for your home page (highly recommended), then this file name need not appear in the URL (for example, the file "index.htm" would be automatically displayed with the URL: "http://www.yourdomain.com/").
Developers using SSI, PHP, or WAP may name their home page "index.shtml", "index.php", or "index.wml".
Important Security Note:
The web server automatically displays a directory "index" of files unless an "index.htm" or "badlocation.htm" file is present. If you wish visitors to access a directory like an FTP archive (displaying icons and and names of available files), then it is very convenient to allow the web server to take over the listing tasks (see SERVING DOWNLOADABLE FILES FROM YOUR WEB DIRECTORY).
It's important to remember that a subdirectory without a default file allows anyone on the Internet to "browse" the subdirectory and disregard your site navigation design. Use an "index.html" or "index.htm" file in subdirectories as part of your normal site architecture. As an alternative, a "badlocation.html" or "badlocation.htm" file can be used to indicate to the visitor that this is a location that he or she could not have reached by following the links on the site. A link should be provided to your home page or to another appropriate page.
4. ORGANIZING FILES IN YOUR HOME DIRECTORY
If you decide to organize your files in subdirectories within your "web" directory, you will have to change the pointers to those files in your HTML code. For example, if you organize your images in an "images" directory (located within your "web" directory eg., /users/<username>/web/images), then you would display that image like this:
<IMG SRC="/images/image.gif"> Level 1 (non-domain) users would use a tag in this format:
<IMG SRC="/~username/images/image.gif">
If the same image file was in the top level of your "web" directory, and not organized within a subdirectory, it would be displayed like this:
<IMG SRC="image.gif">
Most everyone has the need for a web form that can email a report of the visitor's input to a specified address. The instructions below assume that you have a basic familiarity with creating forms using HTML.
We have pre-installed a script in your cgi-bin directory named "mail". This cgi script allows you to easily create custom forms for your web site. The contents of your form are emailed to you when your visitor presses the `submit' button that you have created on your page.
The comments listed at the beginning of the "mail" script provide general instructions for creating your HTML form. Here are detailed instructions for integrating your HTML form with our supported script:
1) Create a text file in your cgi-bin directory named "mail.list". This file will contain a line in this format:
nickname:email_address
The "nickname" is simply a word that serves as an easy reference to an email address. As an example, if you were to use the nickname "joe" and have the contents of the form sent to "jsmith@clearlight.com", then your "mail.list" file would look like this:
joe:jsmith@clearlight.com
This "mail.list" feature provides the best security, and ensures that the form contents are sent only to the address you specify. In addition, this method of specifiying the recipient address prevents it from being read by web crawlers that harvest email addresses for the purpose of spamming.
Be sure to add a carriage return or linefeed to the end of the line (if you don't, the script will leave off the last character of the email address). To do this, just be sure to press "Enter" or "Return" at the end of the line when creating the file in your editor.
2) In the HTML for your form page, the leading <FORM> tag will use a format as indicated in this example (using the nickname "joe" from our previous example):
<FORM METHOD="POST" ACTION="/cgi-bin/cgiwrap/~<username>/mail?joe">
Change the word "joe" in the above URL to whatever nickname you are using in your "mail.list" file, and the word "username" to your username. This will email the names and values of your form fields back to you.
3) You may use any input NAME that you wish for fields in your form. However, the names "subject", "next-url", "from-name", and "from- email" have a special meaning to the mail script. More about how to use these special names is described below.
4) Any input NAME that begins with "require:" will return an error message if not filled out. Any input "name" that begins with "ignore:" will not be reported in the email message. Both can be used as "require:ignore:name". See below for an example.
5) To give that email message a special "Subject:" field, use a hidden value with the name "subject" in your form. We don't want this field to print in the body of the email report, so instead of NAME="subject", we will use NAME="ignore:subject":
<INPUT TYPE="HIDDEN" NAME="ignore:subject" VALUE="Sales Information Request">
6) To provide an acknowledgment screen after your visitor has submitted the form, include the hidden value "next-url" in your form like this:
<INPUT TYPE="HIDDEN" NAME="ignore:next-url" VALUE="http://www.yourdomain.com/acknowledge.html">
This will cause the file "acknowledge.html" to be displayed after your visitor presses "submit" from your form. The "ignore:" prefix causes this field not to be printed in your email report.
7) If desired, you can set the visitor's real name and email address as the "Reply-to" address. This makes it easy to reply to users who fill out your form. To do this, you should use the NAME "from-name" for the field in which visitors enter their real name, and "from- email" for the field in which visitors enter their email address. To make these fields required, we will use the "required:" prefix in the examples below.
<INPUT NAME="require:from-name" SIZE="30">
<INPUT NAME="require:ignore:from-email" SIZE="30">
The last example requires that the visitor enter his/her email address ("require:"), but only uses it in the "From:" header of the email report that is mailed to you. The field is not printed again in the body of the email report ("ignore:").
* * * * *
An added feature of our pre-installed "mail" script is that it allows you to call it directly to display a built-in "message format" (for example: http://www.clearlight.com/cgi-bin/cgiwrap/dick/mail?Richard).
Used in this way, the script is an alternative to the HTML MAILTO tag. Keep in mind that spammers use web crawlers and robots to collect email addresses from MAILTO tags on web pages. Use our pre-installed "mail" cgi script to prevent spammers from easily collecting your email address.
CGI scripts allow interaction with visitors to your site. An excellent source for scripts (both free and commercial) is The CGI Resource Index.
Matt's Script Archive has for years been one of the most popular sources for common scripts, but have well-known security problems and are poorly maintained. We recommend that all users switch to the drop-in replacements for those scripts at nms.
Our system supports user CGI scripts through a program called cgiwrap. This feature allows you to have your own personal cgi-bin directory. You must include cgiwrap in the URL used to run your script. The syntax of your CGI URL would look like this (replace "username" with your own username):
http://www.<yourdomain>/cgi-bin/cgiwrap/<username>/script
The URL above is the long form that could be entered into a browser (referred to as an "external" URL). In your HTML code, you can use a shorter version of the URL that is specific to our web server. The above URL is equivalent to this "internal" URL in this form script example :
<FORM METHOD=POST ACTION="/cgi-bin/cgiwrap/<username>/script">
Cgiwrap is a "wrapper" for the cgi function on our server. By using it, your scripts execute as your username (not the username of the web server). This not only makes the use of user-configurable scripts much safer, but gives added functionality to users. Cgiwrap allows the use of strict owner permissions on scripts and data files (you don't have to make dynamic logs or scripts world-writable or world- readable, for example). Cgiwrap also provides for debugging output directly from the web browser (see below).
Install the script into the cgi-bin directory, and set the proper execution permissions on the file (more information is available in the section below entitled EDITING AND INSTALLING CGI SCRIPTS):
cp script.pl ~joe/web/cgi-bin/script.pl
chmod 700 ~joe/web/cgi-bin/script.pl
The script is executed using a URL like the following example. The account user name is "joe" and Joe's domain is "joesdomain.com":
http://www.joesdomain.com/cgi-bin/cgiwrap/joe/script.pl
If you wish to see debugging output for your CGI, specify cgiwrapd instead of cgiwrap, as in the following URL:
http://www.joesdomain.com/cgi-bin/cgiwrapd/joe/script.pl
If the script is an nph- style script, you will need to run it using a URL such as this example:
http://www.joesdomain.com/cgi-bin/nph-cgiwrap/joe/script.pl
or for debugging output:
http://www.joesdomain.com/cgi-bin/nph-cgiwrapd/joe/script.pl
We've configured cgiwrap so that you may organize your scripts within subdirectories of your cgi-bin directory, if desired. A script may be executed from a subdirectory of your cgi-bin using a URL like the one in this example:
http://www.joesdomain.com/cgi-bin/cgiwrap/joe/subdirectory/script.pl
SPECIAL NOTE: CGI scripts that write new HTML files (such as WWWBoard and other forum scripts) must be modified to work properly on our system. Default permissions on files written through cgiwrap will default to 600 (owner read/write), and cannot be read by the web server. Insert a "umask" command as the first command in your perl script to write world-readable files. For example:
#!/usr/local/bin/perl
umask 022;
Start regular script commands...
CGI FACILITIES
We have several Unix-based CGI facilities available to you:
Perl v5.005 is available at location /usr/local/bin/perl
Perl v4.36 is available at location /usr/local/bin/perl4
Popular perl libraries are installed for your use. These include:
cgi-lib.pl (http://cgi-lib.stanford.edu/cgi-lib/)
Cgi.pm (perl module; type "perldoc CGI")
Cgi_Lite (perl module; type "perldoc CGI_Lite")
libwww-perl (perl module; type "perldoc LWP")
TCL v8.0 is available at location "/usr/local/bin/tclsh8.0".
Older versions of tcl use a similar naming scheme.
6.2 EDITING AND INSTALLING CGI SCRIPTS
You may edit your cgi scripts via telnet (see below), or by transferring the script via ftp and using a text editor on your own computer. The process of editing a script with a local word processor will produce corrupt non-functional scripts unless you follow these two rules:
1) Save scripts only in ASCII format
2) Use only ASCII mode ftp transfer for cgi script uploads and downloads (not Binary or Auto).
When using a word processor such as Microsoft Word to edit your cgi script, use the menu item "File, Save As..." and choose the format "MS DOS Text with Line Breaks". If using Microsoft WordPad you should choose the format "Text Document - MS-DOS Format". The Windows Notepad editor or the DOS Edit program will save in the proper format by default.
After you have modified and saved your script, use your favorite FTP program to upload your script directly to your cgi-bin directory using "ASCII transfer mode".
Once you have transferred the script to your cgi-bin directory, you will need to give the script "owner read-write-execute" permissions. To do this, perform the following steps:
Login to your account via telnet (see the TELNET section below for more information). Type the command:
chmod 700 web/cgi-bin/scriptname
Change the word "scriptname" to the name of the cgi script which you have uploaded. To verify that your script now has correct executable permissions, type this command to perform a "long listing" of the file:
ll web/cgi-bin/scriptname
The system should report back something like this:
-rwx------ 1 <username> users 5854 Sep 7 09:43 web/cgi- bin/scriptname
The "-rwx------" portion indicates that for this file the owner has read (r), write (w), and execute (x) permissions. Owner permissions are all that is required on our system for scripts (or data files read by scripts) called with cgiwrap.
CuteFTP users can select the script file on the server with the program's file browser, and select Commands/Change file attributes. In the "Owner permissions" section of the dialog box, click the check boxes for "Read", "Write", and "Execute". Click the button icon for "Long directory listing" to view the permissions in the format discussed above.
Installation instructions for some cgi scripts may tell you to configure "world write" permission on files (666) or directories (777) in order to function on the average web server. Keep in mind that it's *never* necessary to give "world write" permissions to any file or directory on our system, thanks to cgiwrap. Those permissions allow other users on the system to create or modify account files. For maximum security, use the following permissions instead of the ones given in script installation instructions:
Directories should be chmod 755
Log files should be chmod 600
Web files should be chmod 644
Cgi scripts should be chmod 700
6.3 TROUBLESHOOTING CGI SCRIPTS
You can test your CGI capability with a perl script named "test-cgi". This script passes back variables with information about the web server and remote host you are using. It is included in your web/cgi-bin/ directory. To use it, enter this URL in your web browser (once again, replacing "username" with your own username):
http://www.<yourdomain>/cgi-bin/cgiwrap/<username>/test-cgi
As a troubleshooting example, suppose you have installed your new cgi script, and have created a page that activates it. Let's say that a <FORM METHOD=POST ACTION="/cgi-bin/cgiwrap<username>/scriptname"> tag in your form activates a script that will process user input (as any web form script would do).
You fill out the form, press "submit", and receive the dreaded message "There has been an error... Contact your System Administrator". What should you do?
Cgiwrap can offer useful information in helping you troubleshoot problems with your scripts. You can obtain debugging information from your web browser by using "cgiwrapd" instead of "cgiwrap" in the URL that calls the script. You may see a URL like this displayed in the "Location:" field of your browser at the point you receive the error:
http://www.<yourdomain>/cgi-bin/cgiwrap/<username>/scriptname
In the above example, you could edit the "Location:" field of your browser by inserting the letter "d" at the end of cgiwrap:
http://www.<yourdomain>/cgi-bin/cgiwrapd/<username>/scriptname
You will see now see the details of the variables that your script is processing (debugging output). If you scroll to the bottom of the display, you will see the specific error message(s) generated by your script.
Some scripts will require that you actually edit the tag on your page calling the script so that it now calls "cgiwrapd". In the above example, you could edit your form so that the FORM tag now says:
<FORM METHOD=POST ACTION="/cgi-bin/cgiwrapd/<username>/scriptname">
Now when you press the "submit" button from the browser, the debugging output is displayed. Likewise, "nph-cgiwrapd" is available for debugging scripts that use nph-cgiwrap (for "nph" type scripts that don't output text).
Here's an important point to remember. If you save or transfer a cgi script improperly, the script will simply not function. Some symptoms of a corrupt script are:
The web browser will report an error.
"Cgiwrapd" will report no output.
An attempt to invoke the script via the telnet command line
would result in "file not found".
Viewing the file with the Unix "vi" editor (via telnet) reveals
normally invisible garbage characters at the end of each line.
If this occurs, simply delete the corrupt script from your cgi-bin directory, and save and transfer your script again using ASCII mode.
Imagemaps allow you to have a graphic with "hot spots", which are areas of the graphic that take you to other URLs. You may implement either a "service-side" imagemap (which is compatible with most all graphical browsers) or a "client-side" imagemap (which has better performance and navigation but is not compatible with older browsers). It's good design policy to implement an imagemap as both "server side" (for browser compatibility) and "client side" (for performance and user link feedback).
Here's an HTML example of how to display a server-side imagemap from your web page. This example assumes that the map file and graphic file are both located in the "web" directory.
<A HREF="mymap.map"><IMG SRC="mygraphic.gif" ISMAP BORDER=0></A>
"mymap.map" is the map file created by an imagemap software utility describing the different regions of the graphic and the URLs that they link to. Be sure to use the full URL of the link for each region. Each region will have a line in the map file such as this: rect http://www./filename.html 3,0 78,80
"mygraphic.gif" is the image itself.
BORDER=0 is necessary if you don't want the web browser to draw a border around your graphic.
Just so you know: Our web server doesn't require that you use the old NCSA "/cgi-bin/imagemap" script, but it is supported.
"Client side" imagemaps offer improved functionality, but are only supported by newer browsers. Luckily ISMAP (server side) and USEMAP (client side) tags can be used together without any problem. This provides you and your visitors with the best of both worlds.
For more information on "client side" image maps, see URL: http://www.hotwired.com/webmonkey/html/96/40/index2a.html
We've pre-installed a graphical counter for use by your account. This script is one of many useful CGI scripts available at Matt's Script Archive: http://worldwidemart.com/scripts/. You can place a counter on your home page with this line of HTML code: <IMG SRC="/cgi-bin/cgiwrap/<username>/counter.pl">. Replace the word "username" in the above line with your own account name.
If desired, your counter can be customized for different sizes, borders, digit images, etc. by modifying the "counter.pl" script in your "cgi-bin" directory (see section 6.2 of this user's guide "6.2 EDITING AND INSTALLING CGI SCRIPTS"). Counter configuration information is available at URL: http://clearlight.com/pub/counter/Customize Instructions for installing multiple counters are available at URL: http://www.clearlight.com/multi-counters.txt
If your cgi-bin directory doesn't have a pre-installed "counter.pl" script, contact support@clearlight.com and we'll install it for you.
It's possible to edit your "counter.pl" script to accommodate different digit images. Many of the counter digits available (and on display) at Waidsoft (http://home.waidsoft.com/wsnumbers/) are installed on our server under "/usr/local/digits".
You can modify this line in "counter.pl" to change your counter style:
$digit_dir = "/usr/local/digits/C";
Substitute the "C" in the above line with any of the following:
A, B, C, D, bajbp, banco, banco_glacier, bancored, bluewhite, craig_blue, craig_stony, crest, enya_g, enya_plaid, enya_r, enya_ruby, hanger, iron, ironwood, kosher, orngwhite, slasherc
It's also possible to download and use your own set of custom counter digits. Within each of the above "digits" directories are ten gif files that are named "0.gif", "1.gif", "2.gif", and so on. If you like, you can download alternate GIF images for your counter. You may have to rename any digit images that you download so that they follow the format listed above. Change the "$digit_dir" setting so that it points to a local subdirectory of your account, like this example for the user "joe":
$digit_dir = "/users/joe/counter/digits";
If you have transferred your site from another server it may be necessary to adjust the number displayed by your counter. To do this, simply edit the text file "count.txt" in your counter directory. The number held in this file will be the new starting number for your counter.
Noteworthy sites which offer a large sampling of Java applets are: Earthweb's Gamelan and Jars.
Here's an example of the HTML required to load a very simple applet:
<APPLET CODE=HelloWorld.class></APPLET>
Here's another slightly more complex example:
<applet codebase="applets/NervousText"
code=NervousText.class
width=300
height=50>
<param name=text value="Java is Cool!">
</applet>
Most prewritten applets will have instructions or an example for writing the APPLET tag that will load the java ".class" file. Here are some points to remember about the handling of java ".class" files with your web site:
Server Side Includes (SSI's) make adding dynamic content to your documents easy. SSI's allow you to embed commands in an HTML file that are carried out when the document is served to a browser. Visit the NCSA SSI Tutorial page for more information on server side includes.
SSI's appear in HTML documents within comment tags, beginning with <!-- and ending with -->. They follow this format:
<!--#command tag1="value1" tag2="value2" -->
An HTML document that contains a server side include must have a filename with the extension ".shtml". If you would like to use a server side include on your home page, you may use the filename "index.shtml".
It's possible to use SSI's to execute and include the output of a cgi script in a web page-for example to display a random image (http://worldwidemart.com/scripts/image.shtml ) or a text counter (http://worldwidemart.com/scripts/textcounter.shtml ).
*** The exec SSI command is not enabled for security reasons. *** You may substitute the include virtual command for exec to run a cgi script on our system:
<!--#include virtual="/cgi-bin/cgiwrap/username/scriptname" -->
Here are some other examples of ways to use SSI's:
Last modified: <!--#echo var="LAST_MODIFIED" -->
will display when the current document was last modified.
Today's Date: <!--#echo var="DATE_LOCAL" -->
will print the current date.
<!--#include file="filename.html" -->
will display the contents of a file filename.html at the place where this #include command appears in your current document.
11. SERVING DOWNLOADABLE FILES FROM YOUR WEB DIRECTORY
Here's how to make files available to web users for downloading to their hard drives:
<A HREF="/directory_name">Here's a link to my download directory</A>
When a URL is requested from the web server using only a directory name, files with the following names are searched for in this order: index.html, index.htm, INDEX.HTM, index.shtml, badlocation.html, badlocation.htm. If a file using one of those names is not present, the web server will automatically show a directory index (a list of all the files with icons).
When displaying an automatic index of a directory, the server will first look for the HTML file HEADER.html and include it at the beginning of the index if found, otherwise it will include the plain text file HEADER, if it exists. The same scheme would apply to a file named README.html or README, which will be appended to the end of the directory listing, if it exists.
If your visitor's browser is configured to use the files you are making available, they would automatically view or play the file when they click on it.
An .htaccess text file within your download directory can give you additional control over the way the a directory file index is displayed. For example, you can add a description of each file to the listing by adding this line to .htaccess:
AddDescription "Your description here" file file...
The "AddDescription" directive sets the description to display for a file. File is a file extension, partial filename, wild-card expression or full filename for files to describe. Example:
AddDescription "The planet Mars" mars1.gif mars2.gif
Other directives are also available to further customize automatic directory listings. More information is available at URL:
12. LIMITING USER ACCESS TO A WEB DIRECTORY
You can create a protected directory on your web site that will activate a dialog box on the browser asking for user name and password. Here are instructions for creating a directory named protected to hold files protected by a username and password. This new directory will be created as a subdirectory under your web directory. For security reasons, the file containing user passwords will be created in the top level of your home directory (outside of your web document tree).
Create a directory under your web directory to hold your protected file(s). After completing a telnet login, go to your web directory:
Type: cd web
Create the password protected directory. We are using a directory named protected in this example, but you may use any name you wish.
Type: mkdir protected
In your new directory, create a text file named .htaccess to tell the web server that this directory is going to require user names and passwords. Remember, the leading period in the file name will make this a hidden file.
Go to your protected directory:
Type: cd protected
To create your .htaccess text file:
Type: pico .htaccess
Enter these lines into your text file, replacing the word username with your own username:
AuthType Basic
AuthName "Protected Access"
AuthUserFile /home/username/passfile
<Limit GET POST PUT>
Require valid-user
</Limit>
In pico, exit and save your file:
Press <Control-X> Type "y" Press <Enter>
Go to the top level of your home directory:
Type: cd
Create the password file named passfile:
Type: htpasswd -c passfile userid
In the above command, replace userid with the name that you want to add to the list of allowed users. Htpasswd will then ask you to create and verify the user's password. To add a user to an existing file or to change a user's password, just omit the -c option.
That should do it! Any hyperlink to the protected directory or any of it's files should prompt the browser to ask for a user name and password.
Here's an explanation of the lines contained in your ".htaccess" file:
AuthType BasicThis is a required line.
AuthNameThis word or phrase (spaces are allowed) is displayed on the user's browser when the user is asked for a user name and password, and gives some indication as to the authorization realm, so that the visitor knows which user name and password to enter:
AuthUserFileThis is the full pathname to where an encrypted file holding the passwords is located. If this file was named passfile and was located in the top level of Jose's home directory, this line would be:
<Limit GET POST> Require valid-user </Limit>These three lines tell the web server to look for a valid user name and password in the password file specified by "AuthUserFile".
If you wish to configure multiple password-protected directories and limit access to each directory to a specific user name and password, you can use a Require directive that specifies that user:
<Limit GET POST PUT> Require user username </Limit>For example, to specify that access to this directory should only be allowed to jose, then the directive would read:
<Limit GET POST PUT> Require user jose </Limit>
13. ALLOWING USERS TO UPLOAD FILES TO YOUR WEB SITE
A secure way to allow others to upload small files to your account (less than 1MB) is via HTTP through the use of an upload cgi script. We've modified the upload script and example HTML form from Jeff's Script Archive for our system. They are available at URL:
http://clearlight.com/pub/upload
Edit the FORM tag in HTML upload form upload.html by replacing YOUR_USERNAME_HERE with your own account user name. Edit the CGI script file-upload.cgi and change (at miniumum) the SAVE_DIRECTORY setting to show the path to your upload directory.
For security reasons we recommend that you configure file upload capability only for approved users:
1) Change the file name of the script file-upload.cgi
to something unique.
2) Password-protect the HTML form that activates the file-upload.cgi
script by placing it in its own subdirectory protected by an
.htaccess file. Please see the user's guide
LIMITING USER ACCESS TO A WEB DIRECTORY.
3) Configure the upload location to be a separate subdirectory which
holds only uploaded files. The upload directory should not be the
one that holds the HTML upload form or other regular web site files.
For small searches of just a few pages you may want to consider installing a perl CGI search script such as Simple Search.
Searches covering more than just a few pages can be done faster and more efficiently by using a dedicated search engine such as SWISH-Enhanced. SWISH-Enhanced is a fast, powerful, flexible, free, and easy to use system for indexing collections of Web pages or other text files. Once indexed, you can perform quick searches on your Web pages using the index file.
/home/username/swish.confThen you'll need to edit the following directives:
IndexDir /home/USERNAME/web IndexFile /home/USERNAME/web/swish.index IndexPointer "http://www.YOUR.DOMAIN/" ReplaceRules remove "/home/USERNAME/web"
You should replace /home/USERNAME/web with the actual (full) path to your web files. Most users will simply replace USERNAME with their own account name, and YOUR.DOMAIN with the web site domain name.
No other changes are needed unless you want to fine-tune your search engine (such as omitting files with certain names, etc.). If you read through the config file you'll see the different options, plus help for each one. Any line that starts with a "#" is a comment, and many options are commented out by default.
swish-e -c swish.conf
If all goes well, the index file will be created at the location specified by the IndexFile directive in the conf file.
You'll need to re-index your pages whenever you make changes to them. You can either do this manually every few weeks or so (depending on the frequency of the changes to your web site), or you may want to install the webindex script, which allows you to re-index your site from your web browser. Please give this script a unique name if you decide to use it.
Your search query page is displayed by invoking the swish.cgi script with a URL similar to http://www.YOUR.DOMAIN/cgi-bin/cgiwrap/USERNAME/swish.cgi
.Our Apache web server software allows you to create a custom error message for "404 file not found", and other types of errors. You may create an ".htaccess" text file in the directory where you want to have the custom error messages (such as "web").
Here are some examples of what your ".htaccess" file could contain...
ErrorDocument 404 http://www.yourdomain.com/notfound.htm ErrorDocument 403 http://www.yourdomain.com/forbidden.htm ErrorDocument 401 /unauthorized.htm (401 errors must use this form)
Virtual Server accounts please note:
ErrorDocument 500(cgi script error) directives must be added to the main web server configuration by the system administrator (it won't work from .htaccess). You may request this configuration by sending an email to support@clearlight.com.
You can find all of the various HTTP status codes at URL:
http://www.ics.uci.edu:80/pub/ietf/http/rfc1945.html
See section 9.x for the individual error code explanations.
16. REDIRECTION FOR FILES THAT NO LONGER EXIST
As you develop and evolve your site, it's best to keep the same filenames whenever possible. Search engine indexes can be very persistent in displaying links to files that no longer exist. Regularly changing web file names will result in a large number of File does not exist errors on your usage report, and create frustration for users wishing to access your site from search engine links.
If it becomes necessary to change or remove a file name, you can configure a redirect for the missing file using an .htaccess control file. A text file named .htaccess should be located in the same directory that held the missing file.
Syntax: Redirect old-url new-url
This is one line with three fields separated by spaces:
A Virtual Server account can use this syntax with its own domain name:
Redirect file1.html http://www.yourdomain.com/file2.html
In the above Redirect statement, if the web browser requests file1.html, it will be told to access http://www.yourdomain.com/file2.html instead.
Standard (non-domain) accounts can create one line in an .htaccess file similar to this example (all on one line):
Redirect /~username/file1.html http://www.clearlight.com/~username/file2.html
You will receive a report of your web site usage at the end of the first paid month. Your usage access report is in ASCII format, and provides organized, detailed statistical information about your web site. An explanation of the terms used in your report is available at URL http://blip.cetlink.net/analog/docs/defns.html
Virtual Server Pro clients may request weekly or daily updates to their monthly report at no extra charge. For Standard and Virtual Server account users, weekly updates to the monthly report are available as a US$1 per month option.
We have the ability to customize your report to your needs. If would like to have lower or higher floors for your report, or don't want to have any particular report section included, please let us know. We can also exclude activity from certain hosts or IP addresses.
Most major search engines will use an indexing program (robot) to automatically catalog your site (a notable exception is Yahoo).
It is very important to understand how search engines index your web site. The design of your web site and home page is critical to the ranking that you will receive when visitor search for information relevant to your web site. Detailed search engine information is available at URLs:
The appropriate way to include information about your web pages for indexing or cataloging programs is to use the <META> tag (for describing "meta information") in the <HEAD> part of your web documents. For example, Infoseek now allows you to choose your own keywords and description. To do so, use the META and HEAD tags at the top of your web page as shown below:
<HEAD> <TITLE>The title of your page.</TITLE> <META Name="description" Content="Write your description here"> <META Name="keywords" Content="Write your keywords here"> </HEAD>If your web site is non-commercial, you may go to the newsgroup "comp.infosystems.www.announce" and post a message promoting your site. It is a moderated group, so you will have to follow the general format of the other announcements there. For more information see URL:
Commercial web site owners may find the following resource useful:
Finally, we would appreciate the opportunity to provide a link to your web site on our Client Links page.
If you would like to be listed, send a short note to support@clearlight.com. Please include a short ten word phrase describing your site along with the URL of your welcome page.
Some Telnet software for use with PPP or SLIP is available at URL: http://www.screen.com/understand/telnet.html
Here is an example of how to log into our system using the telnet application built into Windows 2000/XP:
Click Start/Run, and type "telnet" into the field of the dialog box. From the Telnet window, type "open yourdomain.com" (substituting your own domain name for "yourdomain.com"). You will be prompted for your account name and password. To quit your telnet session type "exit". To dismiss the Windows console window type "quit".
Here is an example of how to log into our system using the telnet application built into Windows 9x:
Click Start/Run, and type "telnet" into the field of the dialog box. From the Telnet window, Click "Connect/Remote System...". In the resulting dialog box, you should enter:
Host Name: <hostname> yourdomain.com Port: telnet (select from the pop-up list) Term Type: VT100 (select from the pop-up list)
Be sure to have "VT100" mode set in your emulation software, no matter what telnet application you decide to use. If you have not configured your telnet application for VT100 emulation, or have pressed a key other than "Enter" in step three above, you will receive a "termcap error" message when using a text editor such as "pico" (see below). After entering the above information, click "Connect". This should result in a login prompt from our system (the first of three):
After logging in, you are now in the top level of your 'home' directory. You should then see your shell prompt in the form of "/users/username -->". This prompt will change as you navigate your account directories. It will always show your "current working directory".
At this point, you may type a Unix command, such as "passwd". It is important to change your password immediately with the "passwd" command. Please select a password that is not a word in the dictionary or cannot be easily guessed. The same password is used for your telnet, ftp, and email access.
You can backspace in telnet by using "^H" (Control-H). Better telnet software allows you to configure your "Backspace" key for Control-H. To log out of your telnet session, you may type "exit".
Unix uses case-sensitive file names (lower-case is standard). For example, the file named "index.htm" is considered different from the file named "Index.htm". All file names can have up to 255 characters which can only contain letters, numbers, dots, dashes, and underscores. A helpful Unix command reference is available at UNIXhelp For Users.
Advanced users may take advantage of all of the features of our system, such as the programming environment. Please keep in mind that we do not allow continuous user processes (such as IRC bots) on our system.
- Basic Unix Commands
Here are the Unix commands that are commonly used via Telnet:
/users/usernameThis is your home directory.
web readme"readme" is a file that contains this user's guide. "web" is a directory that will contain your web documents.
Your telnet account has the easy-to-use "pico" text editor available, as well as "vi" and "emacs". These programs allow you to quickly edit your HTML documents on-line if needed. For example, to edit the "readme" file via Telnet, type: pico readme
The commands for using the editor are listed at the bottom of the screen. For example, "^X Exit" means to press the "Control" and "X" keys on your keyboard at the same time to exit the editor and save a file.
- Other Helpful Tools Available Using Telnet
Lynx is a character-mode web browser. Many web users are limited to
using lynx from their shell accounts. To check your page from their
perspective you can type:
lynx http://your.urlIf your HTML editor does not check your pages for valid code you may find "weblint" handy. Weblint will check your pages for any "ragged edges" that a web browser may forgive (for now). To use weblint to check a page that has HTML 3 extensions (such as tables) used by Netscape and others, you can type:
weblint -x netscape http://your.urlWeblint can recognize HTML tags that are specific to Netscape (-x netscape) and Microsoft Internet Explorer (-x microsoft). For more information please consult the man page (type "man weblint").
SECURE POP/IMAP
Software setup guides and configuration help:
http://www.mailtrust.com/support/noteworthy/email-setup
WEBMAIL (Web browser access)
Secure URL: https://webmail.clearlight.com
EMAIL ADMINISTRATION (web browser access)
Secure URL: https://webmailadmin.clearlight.com
OUTGOING EMAIL Your email software must be configured to use SMTP authentication, using the same login as the incoming mail server. If you are unable to send outgoing mail using client software then it is recommended that you change the outgoing server port number setting in your software from 25 to 587. Our SMTP server limits each email account to 200 outgoing messages per hour. Our Outreach email marketing service is available as an option to clients that need bulk email capability.
FORWARDING
Forwarding, as well as many other features can be configured via the
webmail interface (see above). Log in and click the "Settings" link.
MESSAGE DELIVERY LIMITATIONS
Four conditions could cause email to bounce from our mail server, even
if the message has a good delivery address:
1) The receiving account has inadequate disk space.
2) The originating host is listed in one of the major blacklist databases.
In this case you can allow delivery by adding the sender address to your
Spam Filtering Safe Senders list (click Settings from the webmail interface).
3) The originating domain name does not resolve to an IP address.
4) The message is greater than 35MB in size (this equates to a 25MB
attachment size after MIME encryption).
If email is bounced by our server, the error message returned to the sender explains the reason.
EMAIL SYSTEM STATUS
http://www.mailtrust.com/status
Autoresponders return a message automatically to the sender. We have two types of autoresponders. The first type is included as part of your account. You can automatically send an unlimited number of files with it. It works by someone sending email to your Clearlight Communications account with a "Subject:" line that says "send file <filename>" (for example: send file info). The second type of autoresponder requires only an email address (for example: info- username@deva.clearlight.com). It costs $2 per month and can use any available name. This autoresponder provides for immediate email notification to the account owner, as well as logging all requests.
Please be aware that the creation of a ".forward" file in your home directory (to forward email to another address) will cause your autoresponder to no longer work.
Here's how to create your own free autoresponder:
mkdir fileserverThis will be the directory that will hold the files that you want to be sent automatically. For example, when someone sends mail to you with a "Subject:" line that says "send file info", the text file named "info" in the "fileserver" directory will be sent.
send file testYou should automatically receive back the contents of the file via email.
You can use finger to provide simple text announcements to Internet users. You may advertise your finger address to provide instant information that you can customize, such as business information, personal information, or a PGP public key. Any finger client can be used, such as the one included with most Unix systems, or PC software with finger capability, such as Eudora.
The key text file to create is called .plan, and it should reside in the top level of your home directory. Your plan file can contain just about anything you'd like, including information about your company's products or service or your personal credentials; it can even contain a price list and other detailed sales and marketing information.
If someone fingers you from a remote system, our finger daemon will attempt to read and display the text files .plan, .project, and .pubkey which you can create in the top level of your home directory. Users can also put an empty .nofinger file in their home directory, so that an attempt to finger them from a remote system will yield: That user does not want to be fingered.
Your finger address on the Internet is
username@
See the official PHP Manual for complete information.
An HTML document is parsed by the PHP Apache module if the file name has a ".php" extension. If you want your .htm and .html files to be parsed for PHP without changing the file name extension, then create a text file named .htaccess under your web sites document root (for example, ”home/username/web/.htaccess)” containing this line:
AddType application/x-httpd-php htm html
Unlike CGI scripts executed through cgiwrap, the PHP Apache module executes imbedded scripts as the user "web". To see how our PHP Apache module is configured, use the statement <? phpinfo() ?> in a web page that has a ".php" file name extension.
However, when you wish to write or modify a file using PHP, you may wish to use the CGI version of the facility through cgiwrap, so that you can perform the operation using your own account user ID (even though you loose the Apache module performance, it's still faster than perl). This allows you to use secure permissions on writable files.
If you use the Apache Module version of PHP, then a file would require "world write" (chmod 666) permissions so that the web server could change it (writing a new file would require directory permissions of 777). When using the CGI version of PHP with cgiwrap, you can modify files with standard "owner write" permissions (chmod 644) and write files in directories that have standard permissions.
PHP CGI is used like other CGI scripts, except that "php-cgiwrap" is substituted for "cgiwrap". First, move your php file to your cgi-bin directory. Unlike standard CGI scripts, you don't have to change the file permissions to executable. Call the file with a URL similar to:
http://www.clearlight.com/cgi-bin/php-cgiwrap/username/filename.php
In the example above, PHP code in "filename.php" will be processed by PHP CGI. Substitute the word "username" with your own account user name, and "www.clearlight.com" with your own server or domain name. This will allow you to execute PHP commands as your own account ID in the same way that CGI scripts are executed on our system. See the CGI section of the user's guide for more information about cgiwrap.
Clearlight PGP/SSL secure services are an optional facility installed by request. They carry a US$25 setup fee, and are available with no extra monthly service charge to Level 3 Virtual Server Pro accounts. This option is available to Level 1 and Level 2 accounts for $9 extra per month.
This secure services "how-to" outlines how to use the "mail" web form script in your cgi-bin directory to receive secure on-line order information using your own custom forms. The same basic steps would also apply to other "web form" scripts.
In a nutshell: A secure web form is located in your "ssl" directory. The form is configured so that the output is emailed to your primary Clearlight email account with the subject line "Secure PGP". That is all you have to do with your form! This triggers several server-side functions. The email is automatically encrypted and then re-delivered to your Clearlight email account with a different subject heading "Delivered Secure PGP". The encrypted form output can be forwarded to a remote email address if desired (Clearlight support can configure this for you).
Our PGP/SSL secure services setup installs an "ssl" and a ".pgp" directory under your home directory. There is no need to do anything with the ".pgp" directory. It is simply needed to hold a copy of the server's key ring (which holds your public key).
--- SSL
The "ssl" directory is where secure web server documents for your web
site will be stored. Secure documents and scripts are transferred
using SSL security when "https://" is used in the URL. The URL for
documents in your "ssl" directory will be (for example):
https://www.clearlight.com/<username>/filename.html
Please note: Use the appropriate URL for the server you are on:
hpserv: https://www.clearlight.com/<username>/filename.html bardo: https://www1.clearlight.com/<username>/filename.html deva: https://www3.clearlight.com/<username>/filename.html asura: https://www4.clearlight.com/<username>/filename.html
Be sure to substitute your own account name for <username>. For example, if your account name is "joe", then the URL for a secure document might be:
https://www.clearlight.com/joe/filename.html
It is recommended that you place an "index.html" or "badlocation.html" file in your "ssl" directory so that visitors can't "browse" your secure documents using the web server's automatic directory index (by invoking the URL "https://www1.clearlight.com/<username>"). See the user's guide for more information about automatic directory indexing.
To invoke a CGI script using SSL, place it in your cgi-bin directory and call it with a URL based on this example:
https://www1.clearlight.com/cgi-bin/cgiwrap/<username>/scriptname
In order to provide maximum performance for your web site, you should only make select documents and scripts secure (secure documents are very CPU intensive and are served much more slowly than non-secure documents). In order to improve performance, graphics on secure documents should be kept to a minimum. To serve a secure order form you will probably want to call an "https:" URL for three things:
<FORM ACTION="https://www1.clearlight.com/cgi- bin/cgiwrap/<username>/mail?In order for your form contents to be PGP encrypted, you must specify the subject line of your form email as "SECURE PGP" (all caps) using a hidden field:" METHOD=POST>
<INPUT TYPE="hidden" NAME="subject" VALUE="SECURE PGP">
<INPUT TYPE="hidden" NAME="next-url" VALUE="https://www1.clearlight.com/<username>/thankyou.html">
When the secure order form is processed, the encrypted contents of the form are sent with the Subject "Delivered Secure PGP". You will also receive a separate message with the Subject "PGPsendmail response". This is the default PGPsendmail receipt that is delivered when everything is working properly. The "No configuration file found" line in the message is normal. The "PGPsendmail: OK" message is the important line. These receipts can be turned off if you like, but most clients choose to receive them to verify that each order has been processed correctly.
Please Note: A ".forward" file (used for the automatic forwarding of email to another address) will interfere with the operation of PGP services, and should not be used. Please contact support@clearlight.com if you need any help with email forwarding for your specific application.
--- PGP
Merchants must purchase PGP software to easily decrypt email orders
received from the web site. We recommend PGP Desktop Home
available from PGP Corp which can
easily integrate with Outlook, Outlook Express, and Eudora.
Create a compatible PGP key pair by following these steps:
Login to your account via ssh or telnet and execute these commands:
mkdir .pgp cd .pgp pgp -kgFollow the prompts to generate a 1024-bit key pair. When you are done, you'll find these files in your ".pgp" directory:
pubring.pgp (Public Key Ring File) secring.pgp (Private Key Ring File) randseed.bin (Random Seed File)
Download these files to your computer via FTP. Create a separate directory on your hard drive to hold these files, such as "C:\pgp". Move the files into the new directory.
Configure your PGP software to use these key ring files. For example, if you are using PGP for Personal Privacy, click on the "PGPtray" icon in your system tray, and choose "Launch PGPkeys". From the "Edit" menu choose "Preferences...", click the "Files" tab, and set the location for each of the new files.
Send an email to "support@clearlight.com" when you have completed the above steps. We will email you an encrypted test message so that you can test your installation.
After you have successfully tested your PGP for Personal Privacy installation, be sure to make a copy of the three key files onto a floppy disk for safe keeping.
At this point, you should delete the file "/users/<username>/.pgp/secring.pgp" from the server. This file is your PGP decryption "key" and should be safe guarded (it should not be easily accessible by others). Please leave the files "pubring.pgp" and "randseed.bin" in your ".pgp" directory.
MySQL database access is an optional facility available by request. There is no setup fee for this service, and it is available at no extra monthly service charge to Level 3 Virtual Server Pro accounts. This option is available to Level 1 and Level 2 accounts for $9 extra per month.To use our MySQL facility, a developer must have a working knowledge of SQL and program a web interface to the database.
We create raw database with the same name as your account user name, and configure local access from your account. You then create and load database tables and provide hooks to your web site.
The physical data files for your database are located in a directory under your master account named ".mysqldb". You should not disturb this directory or attempt to directly manipulate contained files. All access to your database should be through the mysql program. An exception might apply if your database becomes corrupted, and you need to fix it using the mysql utility "isamchk". See the MySQL reference manual (below) for more information.
By default, we configure "localhost" access to your database. This means that all calls to your database must be from the server where your account is located. If you wish to access your database remotely from an ODBC client (such as Access or Excel), then you must request that we configure your database for remote access. For security reasons, it is best to have us limit remote access to your own ISP domain name or IP address range if possible.
Online resources available at MySQL.com:
A good MySQL book is highly recommended for all users.
FrontPage server extension access is provided to all acounts levels at no extra charge upon request.
Our Unix FrontPage 2002 server extensions do not offer Database or ASP support, but otherwise provide robust FrontPage functionality. Novices and non-programmers will appreciate the ease with which a web site can be created and maintained without coding. Professional developers will find that FrontPage 2003 makes it easy to add advanced elements such as Java, JavaScript, VBScript, ActiveX, Cascading Style Sheets, and Channel Definition Format files.
Users who have requested that their account be configured for access using the FrontPage server extensions have a second separate password for this purpose. This password should be considered somewhat less secure than your regular server account password because it is not protected by a shadow (hidden) password file. Your FrontPage password should be changed on a regular basis, and should be *different* than your regular ftp/telnet/email account password. Change your password in FrontPage Explorer by choosing "Tools, Change Password...".
It is recommended that once you start using FrontPage to create or
modify a web page, you should make it your sole means of updating
the document. If you use ftp/telnet to add a web page after a FrontPage
"web" has been configured for your account, then FrontPage won't be able
to modify the document. This is because FrontPage uses special group
ownership permissions (frntpage) that aren't set when you do a regular
ftp file transfer (the default group ownership is "users"). To fix
the group ownership of a file so that it can be accessed with
FrontPage, you must use the "chgrp" command via telnet:
"chgrp frntpage Some important things to keep in mind once you begin to use the
FrontPage server extensions:
The directories listed below are required by FrontPage, and should not
be disturbed or modified using ftp or telnet:
_private _vti_bin _vti_cnf _vti_pvt _vti_txt images
Many web-hosting providers don't allow ftp/telnet access to FrontPage
accounts because of the support problems that might ensue. We are
offering the FrontPage server extensions as an optional facility so that
developers can pick and choose the best programming tool for the task at
hand. We would prefer to offer the most robust programming environment
possible without limiting developers to any one tool or environment.