Using CGI

In previous versions I've advised using CGI if at all possible. However since v2html 5.0 (and Netscape 4.7 / IE 4.0) the Javascript hierarchy has got a lot more robust, so that's what I use.

The command line option to v2html that makes it use CGI is:

  -c /cgi_script /path_to_html_files 

To use this you must have installed the v2html CGI script on your web-server. The /cgi_script is the name of the CGI script (with path). The /path_to_v_files is the directory where you are putting your html files.

These paths are the paths your web server sees (not the full paths on the system) so is the same path that appears after http://server when accessing the files.

Here's an example:

  cp v2html-cgi /opt/CERNhttpd/cgi-bin/ 
  chmod 755 /opt/CERNhttpd/cgi-bin/v2html-cgi

  cd /home/web/v2html/example/ex1
  v2html -c /cgi-bin/v2html-cgi /v2html/example/ex1 
         -css http://server/v2html/example/ex1/v2html.css
         ../verilog/*.v

Note that v2html can't check the parameters to -c while converting the files. You'll have to do it yourself by viewing the hierarchy in your web browser and clicking on [Hide All] at the top of the hierarchy. Make sure that you view the file using the web server (use http://server/v2html/example/ex1/hierarchy.html rather than file:/home/web/v2html/example/ex1/hierarchy.html).

Also note that you have to specify the full URL to your cascading style sheet using the -css option, like this:

 v2html -c /cgi-bin/v2html-cgi /v2html/examples/millennium_clock/hier_cgi
  -css http://www.burbleland.com/v2html/examples/millennium_clock/hier_cgi/v2html.css
  *.v

If you get a message like this when you click on [Hide All]:

  Bad script request -- neither 
        '/opt/CERNhttpd/cgi-bin/v2html-cg' 
        nor '/opt/CERNhttpd/cgi-bin/v2html-cg.pp' 
        is executable

Then either there is either a problem with the installation of the cgi script or you have incorrectly specified the first parameter to -c.

If you get a message like this:

  v2html error.

then you have probably got the second parameter to -c wrong.

You may also want to use the -k key_string option to v2html. This lets you specify the key to use to stop people looking at hierarchy files that are protected by web-server security. The default is to use a random key, but this means that you can't have bookmarks of the hierarchy at various states (because the bookmark will contain the key, and the key will change each time you run v2html). To get round this problem you can use -k to specify a key_string to use every time. The key can be any string of digits and letters.

CGI security

The v2html-cgi is initially called when a user clicks on the [Hide All] or [Show All] links at the top of the hierarchy file. It then serves the hierarchy back with the folder links in it. Clicking on one of the the folder links calls v2html-cgi again with different parameters to show the hierarchy suitably collapsed or expanded.

This could potentially be a security hole in your server because the file it reads is specified in the URL and v2html-cgi bypasses all the security that your webserver provides.

To minimize the risk I have tried to be as paranoid as possible when writing it so:

• You can't specify .. in the URL, so an intruder can't ask for the 'hierarchy' file ../../etc/passwd and start cracking your passwords!

• It checks that the file is a v2html hierarchy file by checking that it starts with "<!-- v2html hierarchy". This is important because there may be password protected files on your webserver and v2html-cgi could serve them to any old person if it didn't do this check.

• Also, you might have a directory called secret_verilog/ in your web pages which is password protected - what is to stop someone typing in "secret_verilog/hierarchy.html" in the v2html-cgi URL and seeing your secret hierarchy (although they still won't be able see the verilog)? Well, this case is catered for by placing a random "key" in the hierarchy file. When v2html-cgi is called it checks that the key in the URL matches the key in the hierarchy file - this should always be the case because the URL to v2html-cgi should have come from someone clicking a link in the hierarchy file. So, as the intruder can't see the hierarchy file (because of your webserver's password protection) they won't know the key and so won't be able to get v2html-cgi to serve them the hierarchy file.

• Finally, to stop v2html-cgi leaking information through the error messages it returns (for instance about what files exist on your system) I have made sure that it returns the same cryptic error message for all file related errors. You might want to uncomment the more helpful error messages while you're trying to get it up and running!

© 1999-2009 Costas Calamvokis