Linux 2.6 and VPN reference

This list of links was first compiled in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/263).

http://gentoo-wiki.com/HOWTO_OpenSwan_2.6_kernel

http://eole.orion.education.fr/wiki/index.php/Eole_2_Prospect

http://megaz.arbuz.com/archives/2005/01/28/linux-vpn-guide/

UNIX and ports < 1024

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/262).

On UNIX, the ports < 1024 are accessible to user root only.

That has many implications, as then most standard networked servers have to start as root anyway, because they use well-known ports (like HTTP, SMTP, POP, IMAP, FTP, …).

To reduce the risk, most of them then start as root, open the port(s) they need and then change to another user. For example, Apache does it like this.

HOWTO Install and use PHPDoc

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/260).

Introduction

This article is meant for busy people who want to have a go at phpDocumentor. It was written after an install on Windows XP equipped with EasyPHP, but should be very similar in other situations (it’s just a set of PHP scripts after all).

Getting the files

Go get the files on the PHPDoc server (or if you have an OS-specific package, use it). You can grab it from here. Unzip the file and put the directory into your web root (with EasyPHP 1.8, the default is C:\Program Files\EasyPHP1-8\www\).

You should now be able (with EasyPHP actually running) to get to the PHPDoc interface by querying http://localhost/phpDocumentor-1.2.3/.

Setting it up

That’s the first tricky bit. To actually make it work, you need three things:

• The working directory (usually set to the default of c:\program files\easyphp1-8\www\phpdocumentor-1.2.3\docbuilder )
• In “Files” tab, the directory to parse (probably something like c:\program files\easyphp1-8\www\my_sources_directory\)
• In “Output” tab, the output directory (where your doc will be written – something like c:\program files\easyphp1-8\www\mydoc\)

Once this is setup, you should be able to click the Create button in the lower right corner. That should generate your documentation. Now if you want to have a nice shortcut for next time, just bookmark the processing page, as it contains every parameter in the URL, so you will not need to do anything.

The PHPDoc documentation stuff

To have a nice documentation, you should remember three things:

• use a file-level comment AND at least a block-level comment
• use the @package tag in file-level comments
• use documentation blocks of this format:

/**
 * Write a short description here
 *
 * Write a long descrition here, as many lines
 * as you like
 * @package     yourcompany[.the_script_category[.more_defined_category[.blablabla[.blabla[...]]]]]
 * @author      your_name <your_address@domain.com>
 * @todo        One stuff to do in this file (use multiple @todo tags for more)
 */

/**
 * Description of the start of your file.
 *
 * This kind of docblock is better suited for functions, classes and methods,
 * but you must put one (even a blank one) after the page-level block,
 * otherwise it will generate a warning. In this case, let's use some tags as
 * if we were commenting out a function.
 * One can also use HTML in comments for example to <em>emphasize a text</em>.
 * @param   string   $my_string A string parameter the user must pass to the function
 * @param   integer  An integer parameter the user must pass to the function
 * @return  boolean  The value returned by the function (e.g. "True on success, false otherwise").
 * @author  Another author than the file author?
 * @todo    Something to do in this function code?
 */
function my_function($my_string, $my_int){ ...

I think the @package tag is mandatory. All other tags are optional.

Install conclusion

If you respected all these steps, you should now have a wonderful documentation available at http://localhost/mydoc/ Enjoy…

Using the generated doc

You should first try to focus on why you need this doc. I got three scenarii which can help you use the doc at its best, depending on your need.

Pratical cases analysis

Problem A You have just been recruited by a company which has already a huge number of lines of code but no documentation. You will probably need to work on the existing code to fix it or reuse some to develop new features. You thus need to have an index of all existing functions/classes to understand, for example, what the wxyz() function does.
Solution

• Click on [All elements] on the top-right corner (this might change depending on the layout you have been using), then click on [w] to get directly to all elements starting with ‘w’.
• Scroll a bit and find the function.
• Click on its name.
• You get a small explanation of what it does. You also get the file where it is located (so you know where to look for more),

Problem B You want to have a short list of the points you need to get fixed for the next version of your code.
Solution

• Use the @todo tags in your comments before generating the doc.
• In the doc, click on todo on the upper left corner to get to the nice list you wanted

Problem C You want to categorize your software (settings files, administration interface, user interface, …)
Solution

• Use the @package tags in your page level comments before generating the doc.
• Click on the package name on the left menu of the doc. You get a list of features of this package (depending on your comments structure).
• Click on the [index: package] link in the upper right corner to get a list of all files and functions.

Install ViewCVS on RH FC2

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/259).

Introduction

This article is intended to help system administrators with very moderate knowledge of RedHat Fedora (Core 2) install ViewCVS 0.9.3

Getting the file

Apparently, there is no packaged version of ViewCVS for RHFC2 coming from a reliable source, so go get it on SourceForge (in this case, Ireland mirror) – ViewCVS from SourceForge

You can do this like this:

wget http://heanet.dl.sourceforge.net/sourceforge/viewcvs/viewcvs-0.9.3.tar.gz

Trying quick start

Then the ideal solution would be to tell you to read the INSTALL file in the viewcvs archive, but it is pretty incomplete if you want to do it quick. First, the “GUI Operation” section says you can launch viewcvs right now, but this will merely result in a Python error:

Traceback (most recent call last):
  File "/home/ywarnier/viewcvs-0.9.3/standalone.py", line 511, in ?
    import viewcvs
ImportError: No module named viewcvs

Installing

So we have to do the whole install anyway. The “INSTALLING VIEWCVS” section is useful to state what packages should be installed for ViewCVS.cgi to work.

Launch ./viewcvs-install as root user and answer the questions (the default value can be used by pressing “Enter”).

Configuring

Edit /usr/local/viewcvs-0.9.3/viewcvs.conf and change the settings accordingly to your cvs install (probably at least cvs_roots)

Edit /etc/httpd/conf/httpd.conf and add something like

ScriptAlias /viewcvs/ "/usr/local/viewcvs-0.9.3/cgi/"

Fixing missing RCS

Then if you try the alias in a browser (http://localhost/viewcvs/viewcvs.cgi), it might work, but if it doesn’t, it is probably because RCS is not installed on your computer (even if the error is more about something like the files not corresponding to the filter). You can grab a RCS package here or do:

wget http://linuxsoft.cern.ch/cern/7.3.X/i386/RedHat/RPMS/rcs-5.7-15.i386.rpm
rpm -Uvh rcs-5.7-15.i386.rpm

Done

That should work now. Enjoy.

Misc

This article provides with a way to add PHP syntax highlighting in ViewCVS.

HOWTO Configure a DNS server using BIND

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/261).

The config files

named.conf

named.conf.local

zone "example.com" {
        type master;
        file "/etc/bind/db.example.com";
        allow-query { any; };
        allow-transfer { trusted; };
};

db.example.com

Some definitions

SOA
Start Of Authority.

A
…

NS
…

MX
…

CNAME
…

@
The @ is interpreted as the current domain name  [1].

The ending .
What is the difference between example.com. and example.com?
If the name doesn’t end with a dot, BIND append the current domain name.
So example.com. will define example.com while example.com will define example.com.example.com (which is probably not what you want ;-.

[1] BIND knows the current domain name because the db.* file is read based on the zone definition declared in the named.conf.local.

JavaScript: Image rollover

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/258).

Description

Allow to implement images rollovers by simply defining the images of a specific CSS class.
Then you only have to call the function “rollover_register()” and pass it the optional parameters:

• the CSS class you want to trigger. Default: “img.rollover”.
• the pattern you want to add to the original image (e.g.: image.png and image.over.png). Default: “.over”.
• the handler function for onMouseOver. Default: “rollover_over_handler”.
• the handler function for onMouseOut. Default: “rollover_our_handler”.

Code

var rollover_pattern = '.over';

function rollover_register(selector, pattern, over, out)
{
        if (isNaN(selector)) selector='img.rollover';
        if (!isNaN(pattern)) rollover_pattern=pattern;
        if (isNaN(over)) over='rollover_over_handler';
        if (isNaN(out)) out='rollover_out_handler';
        elems=document.getElementsBySelector(selector);
        for (var i=0;i<elems.length;i++){
                addEvent(elems[i],'mouseover',eval(over));
                addEvent(elems[i],'mouseout',eval(out));
        }
}

function rollover_over_handler(e)
{
        // get the source element in a cross-browser way
        if (window.event) {
                img=window.event.srcElement;
        } else if (e.target) {
                img=e.target;
        } else {
                return;
        }
        img.src=img.src.replace(/(\.[a-z]+)$/i,rollover_pattern+'$1');
}

function rollover_out_handler(e)
{
        // get the source element in a cross-browser way
        if (window.event) {
                img=window.event.srcElement;
        } else if (e.target) {
                img=e.target;
        } else {
                return;
        }
        re=new RegExp(rollover_pattern.replace('.', '\.')+'(\\.[a-z]+)$', 'i');
        img.src=img.src.replace(re,'$1');
}

Dependencies

• addEvent()
• getElementsBySelector()

Usage

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
        <title>Image Rollover</title>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15" />
        <script src="../events.js" language="JavaScript" type="text/javascript"></script>
        <script src="../getElementsBySelector.js" language="JavaScript" type="text/javascript"></script>
        <script src="../rollover.js" language="JavaScript" type="text/javascript"></script>
        <script language="JavaScript" type="text/javascript">
        addEvent(window, 'load', function _init() { rollover_register(); });
        </script>
</head>

<body>
<img src="image.gif" class="rollover" alt="image" />
</body>
</html>

JavaScript: getElementsBySelector()

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/257). As of 2008, I don't
remember the source exactly, but the links will lead you to them.

Inspired by Andy, I decided to have a crack at something I’ve been thinking about trying for a long time. document.getElementsBySelector is a javascript function which takes a standard CSS style selector and returns an array of elements objects from the document that match that selector. For example:

document.getElementsBySelector('div#main p a.external')

This will return an array containing all of the links that have ‘external’ in their class attribute and are contained inside a paragraph which is itself contained inside a div with its id attribute set to ‘main’.

So far I’ve only tested it on Phoenix but it seems to work as intended for the small number of test cases I’ve tried. If you spot any bugs please let me know. I’m about to fire up a Windows PC and see how much it breaks in IE…

Update: I’ve put together a demo page showing the function in action. It works fine in IE 6.

http://simon.incutio.com/archive/2003/03/25/getElementsBySelector

JavaScript Libraries

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/256). As of 2008, the most famous JavaScript libraries
are probably Dojo, JQuery and Prototype, but others like MeeBoo, Sarissa and Scriptaculous 
should be considered as well.

Dithered.com – Javascript Library

This is a collection of scripts that I’ve created and/or modified. All the scripts are released under a Creative Commons License. Do whatever you want with them – use them as is or modify them to suit your purposes. Both personal and commercial usage is ok by me.
Unless otherwise noted, all scripts degrade gracefully in older browsers that don’t support the functionality the script provides (ie. no error messages are triggered) and, with the obvious exception of the Browser Detect script, all use object detection instead of browser detection (which ensures a broad range of browsers will run these scripts including future browsers).
Website: http://www.dithered.com/javascript/index.html
Scripts: 1k DHTML API, Acrobat (PDF) Detection / Redirection, Browser Detect, Cookie API, Countdown Timer, Form Functions, Form Validation, Image Preloader, Quicktime Detection / Redirection, Rollovers, Window Opener Functions, Window Properties.
DOM Support / Extensions: Array Extensions, DOM1 Core, DOM2 Events, DOM2 Traversal, DOM2 Views, DOM Extensions.

Scott Andrew – The JavaScript Junkyard

The JavaScript Junkyard is a bunch of silly code I’ve found useful for one reason or the other. Some of them are truly useful, such as the cookie functions, while others are more like adventuresome like inPoly. Many of the geometry and trig-based functions were designed as components for arcade-style DHTML games.
Website: http://www.scottandrew.com/weblog/jsjunk Scripts: sortByProperty, addEvent / RemoveEvent, Cookie Functions, getQueryArgs, getRandomColor, readFile, roundTo, getDistance, getAngle, inPoly.

DomAPI

DomAPI is an application-centric development environment targeted at version 5.0 or better browsers running on Windows, MacOS and Linux. Supported browsers include Internet Explorer, Netscape Navigator, Mozilla, Safari, Chimera and Opera.
Website: http://www.domapi.com/
Licence: Versions <= 3: LGPL; >= 4: ?.

JavaScript: Event Registration

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/255).

Description

Attach an event to an element by defining the type of event to listen for, the handler function to execute when the event is fired, and whether you want to use event capture.

Code

/* Author: Scott Andrew LePera (www.scottandrew.com)
Default value for useCapture has been set to false because: "If it is true,
the event listener should not fire for any element the event listener is
registered on." */
function addEvent(obj,evType,fn,useCapture){
        if (isNaN(useCapture)) useCapture = false;
        if (obj.addEventListener){
                obj.addEventListener(evType,fn,useCapture);
                return true;
        } else if (obj.attachEvent){
                var r=obj.attachEvent("on"+evType,fn);
                return r;
        } else {
                alert("Handler could not be attached.");
        }
}

function removeEvent(obj,evType,fn,useCapture){
        if (isNaN(useCapture)) useCapture=false;
        if (obj.removeEventListener){
                obj.removeEventListener(evType,fn,useCapture);
                return true;
        } else if (obj.detachEvent){
                var r=obj.detachEvent("on"+evType,fn);
                return r;
        } else {
                alert("Handler could not be removed.");
        }
}

Usage

function windowOnLoad(){
        // Some stuff
}
addEvent(window, 'load', windowOnLoad);

Links

• Crossbrowser DOM Scripting: Event Handlers (by Scott Andrew LePera)
• Call of the wild (scripts)