With the recent fall update for the XBox 360, Microsoft has opened you its Media Client to allow it to connect to third-party UPnP Media Servers. Which is awesome, except for the fact that the XBox 360 only supports WMV (and MPEG) encoded movies. I mean seriously, no “person” voluntarily uses your media formats Microsoft. And with the 360’s horsepower, there shouldn’t be a problem here to decode these things in software. What’s a gamer to do?

Thankfully a group, with a little piece of software called TVersity, recently added transcoding capabilities and support for the XBox 360 Media Client to allow for transcoded videos to be streamed to the XBox 360 on demand. As the little man rejoices and struggles to get it all to work, I write a guide on what I needed to do to unlock this desirable capability.

Note: The programs and versions used in this guide are:

• Windows Media Player 11
• K-Lite Codec Pack 2.84 Full
• TVersity 0.9.9.2
• XBox 360 w/ Fall 2006 Update

Uninstall Everything

It is highly recommended that you reinstall Windows Media Player, even if you already have 11 installed. Don’t ask why, but many people who were having trouble have gotten it to work by reinstalling everything. To do this, go to Control Panel -> Add or Remove Programs. First, uninstall any programs that start with “Windows Media”. Secondly, go to the “Add/Remove Windows Components” tab and uncheck “Windows Media Player” (click Next to uninstall). I recommend restarting your computer once this is all done.

One of the things that I have noticed in my testing is that TVersity is extremely picky in its codecs. Therefore, (and this really isn’t optional) uninstall all exisiting codecs and codec packs from your system. Yes, that means DivX, Xvid, ffdshow, and/or any packs that contains codecs. If you have no idea what a codec is, chances are you have never installed one. However, it is best to look for programs with the aforementioned names in case your or someone else has installed one.

Prerequisites

TVersity works best with Windows Media Player 11 and Windows users can download this program for free from Microsoft’s website. The install is fairly straight forward and shouldn’t need explanation. On a side note, WMP has come a long ways since its earlier days and version 11 is a very well polished, fast media player. After having used Winamp my entire life, I was almost swayed to actually start using Microsoft’s latest media player. (Almost, being the important word here as nothing beats the old Winamp/VLC combo)

Next, your going to need the proper codecs to decode your movies for transcoding. After playing with a couple codec packs, I have had the best success with the K-Lite Codec Pack Full. When installing this pack, during the installation customization phase, be sure to uncheck the first DivX and XviD checkboxes as TVersity prefers to use ffdshow to decode its videos. Since ffdshow already decodes these formats, its best to not install the seperate codecs. (Remember, TVersity is picky with its codecs. I was unable to get it to work with the official DivX and XviD codecs.)

Installation & Setup

Next, install the latest version of TVersity from the official website. This is also very straight forward, but requires some setup before using.

When the installation is done, stop the Media Server by going to All Programs -> TVsersity Media Server -> TVersity Tools -> Stop TVersity Media Server. Next, edit the file C:\Program Files\TVersity\Media Server\profiles.xml using notepad and find the line:

        <transcodetarget audio="audio/L16" video="video/x-ms-wmv" photo="image/jpeg"
                         onlineAudio="audio/mpeg" onlineVideo="video/x-ms-wmv" onlinePhoto="image/jpeg"/>

To the end of this tag, add actualSizeMatchFileSize="true" to produce the following:

        <transcodetarget audio="audio/L16" video="video/x-ms-wmv" photo="image/jpeg"
                         onlineAudio="audio/mpeg" onlineVideo="video/x-ms-wmv" onlinePhoto="image/jpeg" actualSizeMatchFileSize="true"/>

Restart the media server by redoing the previous instructions, except selecting Start TVersity Media Server instead.

You can launch the TVersity frontend by the icon on your desktop or All Programs -> TVsersity Media Server -> TVsersity Media Server. From within this program, you can modify the TVersity trancode settings from the Settings tab on the main screen, and clicking on Transcoder on the left. For a typical setup where you have a moderately fast computer and your XBox 360 is connected via a network cable, I would recommend the following settings:

• Select: Transcode only when needed
• Uncheck: Decrease the bitrate if it is too high for my network
• Select: Optimize: Quality
• Select: Connection Speed: Wired (100 mbps)
• Select: Connection Quality: Excellent
• Select: Compression: Minimum
• Enter: Video Resolution: 1280 x 720
• Uncheck: Decode the media as fast as possible without taking into account its bitrate

Click save in the bottom right to save your changes.

Don’t forget to add some test content - I would recommend adding DivX, XviD, MPEG 2 & 4, and WMV encoded videos to make sure everything transcodes properly. TVersity also supports MP3s and SHOUTcast streams, which are nice to stream while gaming.

Connect the 360

To connect the XBox 360 to TVersity, got to the Media blade and select Videos. On the device page, select Computer. It’ll give you some direction on how to install Windows Media Connect, which you can promptly ignore and select Yes. The 360 will search for your TVersity Media Server. If it can’t find it, make sure your computer and 360 are connected to the same network, through a switch/router (don’t direct connect / crossover), and that your firewall is either disabled or allows incoming network traffic on TCP port 41952.

Once connected, you should be able to see the list of shared movies added to TVersity. Selecting a movie and playing it should start the movie after a short (< 10 seconds) time. If you get an error saying that the media format is not supported, or a black screen with nothing happening, then you likely have a codec problem and should go back to the first (Uninstall Everything) step and start over. Be sure to try out all your differently encoded content before freaking out to see if it is only one codec that is giving you trouble. For me, I couldn’t get XviD content to decode because I installed the XviD codecs from K-Lite instead of using ffdshow to decode it.

You should also note that due to the way your videos are transcoded, you can not fast-forward / rewind videos. TVersity also seems to have a bug where the XBox 360 Media Player will not end immediately after a video is done. Small things to overlook for streaming media to your XBox 360.

Other Thoughts & Conclusion

If you have Window XP Media Center Edition, and think TVersity is too much of a hassle, I would recommend looking into Transcode 360 as from what I have heard it is easier to setup, but not as nice to use. Or else you can look into VLC360 (which I have not).

The unfortunate thing about all of these solutions is that it requires a Windows XP (or Vista) computer in order to work as there currently is no Linux based solution. I have been looking into this however, and based on my time from playing around with TwonkyVision’s TwonkyMedia, I believe it is possible that with a little bit of CGI scripting you could have it transcode videos on-the-fly using either VLC, mencoder, ffmpeg, etc. I don’t have the time to play with something like this but, if someone is willing to give it a try, let me know how it turns out!

VPNC

VPNC has been backported to the White Russian release (although poorly), and can be installed using ipkg. To install, first edit /etc/ipkg.conf and add the following line after the other “src” lines:

src backports http://downloads.openwrt.org/backports/rc5

Now to install vpnc:

ipkg update
ipkg install libgcrypt
ipkg install kmod-tun
ipkg install vpnc

The first two installs are required packages that aren’t (for some reason) installed when you install vpnc. If you try running vpnc right now, you’ll get the error:

can't open /dev/net/tun, check that it is either device char 10 200 or (with DevFS) a symlink to ../misc/net/tun (not misc/net/tun): No such file or directory
can't initialise tunnel interface: No such file or directory

vpnc requires the kernel module tun. The vpnc installer adds an entry to /etc/modules.d/ to auto-install the module on startup, but it won’t be started after you install it. To install to so we can use it right now, run:

insmod tun

The configuration settings for vpnc are located in /etc/vpnc/. Open vpnc.conf with an editor (like vi) and add/edit the follow configuration settings: (replace the IP/usernames/passwords with your VPN credentials)

Interface name tun0
IPSec gateway 12.34.56.78
IPSec ID globaluser
IPSec secret globalpass
Xauth username myuser
Xauth password mypass

Now (at the time of this writing), if this package had been setup properly, this would be all we would have to do for vpnc, and we could just run the command vpnc to start the VPN service. However, if you try doing this now, vpnc will fail to find the vpnc.conf file because it is hard-coded to look for /etc/vpnc.conf. We fix this easily by running:

ln -s /etc/vpnc/vpnc.conf /etc/vpnc.conf

Also, when vpnc runs, it trys to write its PID information to /var/run/vpnc/ which doesn’t exist. We can fix this by running:

mkdir /var/run/vpnc

Were not done yet, and this is the big one. After vpnc connects to the VPN server, it will run /etc/vpnc/vpnc-script. The problem is that this file was originally written for a Bash environment, but OpenWRT only has sh. If you try running vpnc, you will get the following error:

/etc/vpnc/vpnc-script: 222: Syntax error: Bad for loop variable

Luckily, there’s only two places in the code that cause conflict with this environment. We will need to edit the vpnc-script and change the two (2) instances of this code…

                for ((i = 0 ; i < CISCO_SPLIT_INC ; i++ )) ; do
                        eval NETWORK="\${CISCO_SPLIT_INC_${i}_ADDR}"
                        eval NETMASK="\${CISCO_SPLIT_INC_${i}_MASK}"
                        eval NETMASKLEN="\${CISCO_SPLIT_INC_${i}_MASKLEN}"
                        set_network_route "$NETWORK" "$NETMASK" "$NETMASKLEN"
                done

…to…

                i=0                                                        
                while [ $i -lt $CISCO_SPLIT_INC ] ; do             
                        eval NETWORK="\${CISCO_SPLIT_INC_${i}_ADDR}"
                        eval NETMASK="\${CISCO_SPLIT_INC_${i}_MASK}"
                        eval NETMASKLEN="\${CISCO_SPLIT_INC_${i}_MASKLEN}"
                        set_network_route "$NETWORK" "$NETMASK" "$NETMASKLEN"
                i=`expr $i + 1`
                done

Alrighty, we’re done. If you run vpnc right now, it should connect and run as a daemon (without throwing any erros). To disconnect, use vpnc-disconnect.
Note that vpnc-script modifies your routing table (route) and your DNS resolutions (/etc/resolv.conf) on connection. You may need to modify this script as necessary.

Shorewall

Now that we have vpnc configured, lets setup Shorewall.

First we will create a zone for the VPN in /etc/shorewall/zones …

vpnc  ipv4

…, and map the zone to the interface in /etc/shorewall/interfaces:

vpnc  tun0  detect

The configuration file /etc/shorewall/tunnels is used to specify the VPN tunnels your firewall will be allowing through. The second argument is the zone in which the VPN gateway is behind, and the third argument is the IP of the VPN gateway. Chances are you won’t need the second line, but I added it there just incase. (You may also need to change udp to tcp, depending on your VPN Concentrator settings)

generic:udp:500    wan  12.34.56.78
generic:tcp:1723  wan  12.34.56.78

Lastly you will need setup any masquerading in /etc/shorewall/masq if you want to access the VPN from local network:

# If the lan and wifi are bridged
tun0    br0
#If you have removed the bridge (seperated them)
tun0    vlan0
tun0    eth1

Were done! Restart Shorewall using shorewall restart and the rules should be applied. We can now run vpnc to setup the VPN connection, and you should be able to connect to the servers behind it.

If you would like vpnc to be started on startup of Shorewall, add the following:

/etc/shorewall/start

vpnc

/etc/shorewall/stop

vpnc-disconnect

Conclusion

Despite the problem with the VPNC package, its not too difficult to setup a VPN connection with a Cisco VPN Concentrator. If your VPN gateway timeouts after a period of inactivity, you may need to setup a watchdog service that sends small traffic through the tunnel every so often. Your mileage may vary.

I hope my article was helpful. Please leave comments!

• I don’t treat the xmlns property any more special then any other property. The original BadgerFish spec states that the xmlns property should be on every node. This is overkill for me, so I left it out.
• I don’t ignore whitespace text nodes.
• Multiple child text nodes are added to the ‘$’ property as an array.

For limitations of BadgerFish, see the homepage.

Usage example:

<script language="text/javascript" src="BadgerFish.js"></script>
<script language="text/javascript">
document.write(encode(document).toSource());
</script>

This is not the best JavaScript I’ve ever written, as I could have cleaned it up using namespaces and JavaScriptDoc comments, but I wrote it in a hurry. Feel free to tear this apart and use it for your own purposes.

Click here to download.

Controlling the Network Switch

If you’ve had a chance to look at the hardware layout of the WRT54GL, you will notice that the router uses VLAN tagging to seperate the WAN port from the rest of the switch. This VLAN configuration settings are stored in NVRAM and, as such, we can modify them to our heart’s content. The WRT54G series router’s switch supports up to 15 VLAN tags which, since there are only 6 switch ports, is overkill. By default, your router will have the following vlan configuration settings: (you can get/set these using nvram)

vlan0ports="3 2 1 0 5*"
vlan0hwname=et0
vlan1ports="4 5"
vlan1hwname=et0

For a quick explanation; Each vlan’s setting are defined in vlan[#][setting]. Ports defines which ports belong to that vlan, and must always include port 5 or the vlan will not be able to talk to the router (making it essentially useless). The asterisk next to the 5 at the end of the ports list indicates that this vlan is the default vlan. Hwname is the physical port the switch is connected to, and should always be et0 for the WRT54GL.

If you would like to add a DMZ to your router, you can set your nvram settings as such: (this makes port 4 (internal 0) the DMZ)

vlan0ports="3 2 1 5*"
vlan0hwname=et0
vlan1ports="4 5"
vlan1hwname=et0
vlan2ports="0 5"
vlan2hwname=et0

Now that you have the vlan tagging setup properly, you will need to initialize the interface within OpenWRT. First, setup your configuration options for the DMZ zone:

dmz_ifname=vlan2
dmz_proto=static
dmz_ipaddr=192.168.3.1
dmz_netmask=255.255.255.0

Then, make sure in /etc/init.d/S40network that the following line exists:

ifup dmz

At bootup, when the S40network script is run, ifup will look for all nvram settings starting with dmz_ and use them to initialize the interface. It is also smart enough to look at [name]_ifname and determine if it is ethernet interface, vlan, or bridge.

For example, if you look at your lan settings (nvram show | grep "lan_"), it will look something like this:

lan_ifname=br0
lan_ifnames="vlan0 eth1 eth2 eth3"
lan_proto=static
lan_ipaddr=192.168.1.1
lan_netmask=255.255.255.0

What’s happening here is that the lan interface is a bridge of vlan0 (LAN) and eth1 (Wifi). (Don’t ask about eth2 & eth3, I have no idea why they are there)

If you would like to seperate the LAN from the Wifi network, change your settings to:

lan_ifname=vlan0
lan_ifnames="vlan0 eth2 eth3"
lan_proto=static
lan_ipaddr=192.168.1.1
lan_netmask=255.255.255.0
 
wifi_ifname=eth1
wifi_proto=static
wifi_ipaddr=192.168.2.1
wifi_netmask=255.255.255.0

Then make sure /etc/init.d/S40network has the following line within it:

ifup wifi

Just reboot and your seperated.

Note that if you are adding more zones to your router, you should also configure your other services such as firewall script and DHCP client to take advantage of the new configuration.

For dnsmasq, you should add something like the following to /etc/dnsmasq.conf:

dhcp-range=lan,192.168.1.100,192.168.1.199,255.255.255.0,24h
dhcp-range=wifi,192.168.2.100,192.168.2.199,255.255.255.0,1h
dhcp-range=dmz,192.168.3.100,192.168.3.199,255.255.255.0,24h

You should also allow the “safe” zones to talk among each other by adding the following firewall rules to /etc/init.d/S45firewall:

...
WIFI=$(nvram get wifi_ifname)  #add if LAN/Wifi are seperated
DMZ=$(nvram get dmz_ifname)  #add if you have a DMZ zone
...
#replace references to br0
iptables -A FORWARD -i $LAN -o $LAN -j ACCEPT
iptables -A FORWARD -i $LAN -o $WAN-j ACCEPT
 
#add if wifi is seperated
iptables -A FORWARD -i $LAN -o $WIFI-j ACCEPT
iptables -A FORWARD -i $WIFI-o $LAN -j ACCEPT
iptables -A FORWARD -i $WIFI-o $WAN-j ACCEPT
iptables -A FORWARD -i $WIFI-o $WIFI-j ACCEPT
 
#add if dmz is available
iptables -A FORWARD -i $LAN -o $DMZ -j ACCEPT
iptables -A FORWARD -i $WIFI -o $DMZ -j ACCEPT  #if wifi is also seperated
...

Firewall Made Easy

Despite your experience with iptables, this network routing program is hard to read and even harder to remember all the switches when its time to add a new rule to your firewall. Thankfully there is a much easier way to configure your firewall, and it’s called Shorewall.

The Shoreline Firewall, more commonly known as “Shorewall”, is a high-level tool for configuring Netfilter. You describe your firewall/gateway requirements using entries in a set of configuration files. Shorewall reads those configuration files and with the help of the iptables utility, Shorewall configures Netfilter to match your requirements.

You can download one of the latest builds of Shorewall for the OpenWRT from Fabio Longarai’s OpenWRT site. To install Shorewall, it’s as simple as:

cd /tmp
wget http://openwrt.homelinux.net/shorewall_x.x.x_mipsel.ipk
ipkg install shorewall_x.x.x_mipsel.ipk
rm shorewall_x.x.x_mipsel.ipk

Note that the following guide was written for Shorewall v3.0.4-2.

All your configuration files can be found in /etc/shorewall/. Since every person’s needs and router settings are unique, their firewall will be unique as well. As such, the following configuration settings are stereotypical settings only and should be customized to one’s needs. For more information on configuring Shorewall, please see the official documentation.

For beginners to Shorewall, I recommend tackling the firewall files in the following order:

zones

This file specifies the available zones you want to control by your firewall. The names of zones are nothing more then aliases, and as such Shorewall has no understanding of the meaning of them. Do not assume a zone called DMZ will behave like a DMZ zone.

###############################################################################
#ZONE   TYPE            OPTIONS         IN                      OUT
#                                       OPTIONS                 OPTIONS
fw      firewall
lan     ipv4
wifi    ipv4
dmz     ipv4
wan     ipv4
#LAST LINE

policy

This file defines the default behavior for a zone. Any zone is allowed to talk to itself, so you don’t need to specify a zone in both the source and destination. Also, (assuming your networking is A->FW->B) just because A can talk to FW, doesn’t mean that A can talk to B - you must explicitely define it.

You can also, in this file, define what the default behavior of traffic being forwarded from one zone to another is and the type of logging the firewall does.

###############################################################################
#SOURCE         DEST            POLICY          LOG             LIMIT:BURST
#                                               LEVEL
fw      all     ACCEPT
lan     all     ACCEPT
wifi    all     ACCEPT
dmz     fw      ACCEPT
dmz     wan     ACCEPT
dmz     all     REJECT  notice
wan     dmz     ACCEPT
wan     all     DROP
all     all     REJECT  notice
#LAST LINE

interfaces

In this file, you define the interfaces and how they map to the available zones. You can also specify options on restricting what types of erronious traffic can be let through.

###############################################################################
#ZONE   INTERFACE       BROADCAST       OPTIONS
lan     vlan0   detect  routeback,dhcp
wifi    eth1    detect  routeback,tcpflags,dhcp,routefilter,detectnets,nosmurfs
dmz     vlan2   detect  routeback,dhcp
wan     vlan1   detect  routeback,tcpflags,blacklist,dhcp,routefilter,nosmurfs
#LAST LINE

masq

This file defines how source NAT-ing is done through the firewall, and through which interface.

###############################################################################
#INTERFACE              SUBNET          ADDRESS         PROTO   PORT(S) IPSEC
vlan1     vlan0
vlan1     eth1
vlan1     vlan2
#LAST LINE

rules

This is the brain of your firewall, where you define the complicated exceptions to the default policy and let traffic through. A lot can be done in this file, so be sure to read up on it. For this example, I’m going to allow pings to the firewall, and incoming BitTorrent to my main system. The first rules uses a macro while the second is a typical rule that employs DNAT-ing.

#############################################################################################################
#ACTION SOURCE          DEST            PROTO   DEST    SOURCE          ORIGINALRATE            USER/
#                                               PORT    PORT(S)         DEST   LIMIT            GROUP
#SECTION ESTABLISHED
#SECTION RELATED
SECTION NEW
Ping/ACCEPT     wan     fw
DNAT            net     lan:192.168.1.100 tcp     6881:6889   -
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

routestopped

The rules in this file define the default behavior when Shorewall is stopped. For the most part, to allow “safe” zones to talk properly when Shorewall is stopped, added them to this file as so:

###############################################################################
#INTERFACE      HOST(S)                 OPTIONS
vlan0   -       source
eth1    -       source
vlan2   -       source
#LAST LINE    

tos

Unfortunately, OpenWRT’s iptables does not support TOS, so don’t bother adding any entries to this file.

params

For the most part, if you are doing basic firewalling, you can ignore the rest of the files in this folder. The only other file you may be interested in is params, where you can define variables to be used in the other config files in this directory. For example, you could put in this file…

$LAN_ZONE=lan
$LAN_IFNAME=$(nvram get lan_ifname)
$LAN_BROADCAST=192.168.1.255
...

… and then, you could use these variables in your scripts …

/etc/shorewall/interfaces:
...
$LAN_ZONE    $LAN_IFNAME    $LAN_BROADCAST    $LAN_OPTIONS
...

… in order to simplify the changing of your network configurations.

Traffic Control

One of my primary goals of setting up a dedicated firewall was to have Traffic Shaping/QoS determine the priority of my internet traffic and adjust accordingly based on the needs to the network. For example, my primary network traffic is VoIP, BitTorrent, and HTTP/web. I want VoIP to have the highest priority of my network communications, while BitTorrent to be the lowest. Therefore, my phone conversations won’t drop when I’m downloading heavy.

In order to use traffic shaping, you must have the tc package installed. You can do this by running:

ipkg install tc

It should be noted before you start that you can only shape outbound traffic. You may ask why, but think about how a network works. The router can only make a decision on what packet has priority over another packet when it has received that packet and examined it. Therefore, it does not make sense to shape incoming traffic since a)your internal network is likely must faster then your incoming internet traffic thus making prioritization useless, and b) you’ve already received the packet, so you might as well just send it on its way (your ISP has determined which packet was important to go down the line first).

tcdevices

First, you need to define the devices on your router you would like to enable traffic shaping on. You can do this by editing the tcdevices config file:

###############################################################################
#INTERFACE      IN-BANDWITH     OUT-BANDWIDTH
wan     5mbit   512kbit
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

You should set these settings to your theoretical maximum speed on that line. If traffic starts moving faster then these defined settings, the router will begin dropping packets in order to slow down the traffic.

tcclasses

For my purposes, I created five “buckets” to prioritize my traffic in. Note that a higher priority will get served first (till its empty) before a lower priority is served. In the example below, priority 4 is the default priority and all unmarked traffic will go into this priority queue. I also auto-marked all (small) ACK packets as highest priority to artifically speed up downloads.

###############################################################################
#INTERFACE      MARK    RATE    CEIL    PRIORITY        OPTIONS
br1     1       full    full    1       tcp-ack #CRITICAL
br1     2       full    full    2               #HIGH
br1     3       full    full    3               #NORMAL
br1     4       full    full    4       default #LOW
br1     5       full    full    5               #USELESS
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

tcrules

Finally, this is the file where we specify how our traffic is prioritized. I wanted my VoIP traffic to be priority 2, my common internet traffic as priority 3, and my BitTorrent traffic and everything else as 4. The reason I did not make priority 3 my default and then just (add rules to) put BitTorrent in priority 4 is due to the fact that my BitTorrent client does not allow me to define the source ports of outbound traffic. So instead, any unrecognized traffic gets low priority.

In the example below, I specify that Pings & Rdate (time update) requests are highest priority, VoIP traffic & DNS requests are next highest, my common internet traffic (HTTP, SSH, FTP) are next, and everything else is last.

###############################################################################
#MARK   SOURCE          DEST            PROTO   PORT(S) CLIENT  USER    TEST
#                                                       PORT(S)
1       vlan0,eth1      0.0.0.0/0       icmp    8               #Ping
1       vlan0,eth1      0.0.0.0/0       tcp     37              #Rdate
2       vlan0           0.0.0.0/0       udp     5060:5061       #VoIP
2       vlan0           0.0.0.0/0       udp     16384:16482     #VoIP
2       vlan0,eth1      0.0.0.0/0       udp     53              #DNS
2       vlan0,eth1      0.0.0.0/0       tcp     53              #DNS
3       vlan0,eth1      0.0.0.0/0       tcp     80              #HTTP
3       vlan0,eth1      0.0.0.0/0       tcp     22              #SSH
3       vlan0,eth1      0.0.0.0/0       tcp     20              #FTP-DATA
3       vlan0,eth1      0.0.0.0/0       tcp     21              #FTP
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

For more advanced rules, see the docs.

Conclusion

Last thing, in order to start using Shorewall, use the command shorewall start. If you would like to have Shorewall start on bootup, add the following code to /etc/init.d/S46shorewall. (Don’t forget to make it executable: chmod a+x S46shorewall)

#!/bin/bash
shorewall start

Please note that you can easily prevent yourself from accessing the CLI with Shorewall. And if Shorewall starts on startup, a reset will not fix the problem. Please thoroughly test your firewall scripts before auto-starting shorewall on startup.

Well, its getting late and I need to crash. I hope you enjoyed the article, and look forward to reading your comments. If you would like more information on a particular section, feel free to drop me a note and I’ll look into updating it. Later!

One of the most popular third-party firmware available is OpenWRT. This firmware is essentially a stripped-down embedded Linux operation system with addon packages to allow it to be a wireless router. It’s small, simple, and powerful; though not for the light of geek, as any configuration must be done by CLI.

I recently got a WRT54GL wireless router, which is the same as a WRT54G v4 router. (Linksys changed the model number since v5 does not use Linux and will not run custom firmwares.) In only a few hours, I was able to install OpenWRT and setup a powerful router/firewall for my home network. Here’s how you can too…

Installing OpenWRT

There are two ways to install OpenWRT: the easy way, or the safe way. Now, one should follow the safe way as it is, hence, safe. However, it is also the most difficult way. Essentially what you want to do is reflash the router using TFTP; that is, if something goes wrong during the flash, you can just try again. In order to do this method, you need to enable boot_wait on the router. There used to be a very easy way of doing this on the older WRT54G routers using the Ping hack. However, Linksys has such patched this vulnerability and the only way to enable this feature is to downgrade the router to a previous version (< 3.01.3).

Now, the easy way is to just use Linksys’ Firmware Upgrade page and upload OpenWRT to the router. The only problem with this method that is if anything goes wrong you’ve got a bricked router. However, as long as you don’t bump any cords, use a bad firmware, or loose power during the flash and powerup, things will be fine. Since no challenge is without its risks, I decided to go about this route.

You can download the latest version of OpenWRT from the official website at http://downloads.openwrt.org/.

Note that this document is written for the WhiteRussian release.

The are several different versions of the firmware available depending on the hardware and filesystem configuration you want. The WRT54GL is the same as a WRT54G, so download the WRT54G firmware. There is also two different filesystem configurations you can have.

SquashFS is the recommended, more secure setup as it has a two part filesystem. One area is read-only which contains all the files that came with the firmware, while the other area is read/write which is the root of the file system and contains symlinks to the read-only files. OpenWRT recommends this setup since it reduces the chance of one rewritting something they shouldn’t. However, it also doesn’t restrict the normal usage as you can remove the symlinks and replace the file with one of your own (the extra step offers accidental protection). This is the setup I went with.

For completion sake, the JFFS2 setup is just a normal read/write filesystem that doesn’t offer a proper failsafe mode.

By using the Linksys Firmware Upgrade page on the router’s web administration pages, select the firmware to be uploaded and click on “Update”. It takes awhile to reflash the router so don’t hold your breath. At first, the textbox on the bottom will show somewhat of a progress bar. When the bars reach the end of the text field, the page will change indicating the router has been updated. DO NOT DO ANYTHING! Look at your router. If the DMZ light is on, it means that OpenWRT is booting up. It will take some time to start and initialize so you must be patient some more. You are not free to do anything until the DMZ light turns off and the router is operational. Then, and only then, can you proceed to the next step.

First thing you should do is log into the router via telent. (Remember, OpenWRT is primarily a CLI OS, so get comfortable with it) You should be able to access it by the previously set IP address, and no password is required (yet).

root@localhost:~$ telnet 192.168.1.1
Trying 192.168.1.1...
Connected to 192.168.1.1.
Escape character is '^]'.
 
BusyBox v1.00 (2005.09.22-14:58+0000) Built-in shell (ash)
Enter 'help' for a list of built-in commands.
 
  _______                     ________        __
 |       |.---–.---–.---–.|  |  |  |.----.|  |_
 |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
 |_______||   __|_____|__|__||________||__|  |____|
          |__| W I R E L E S S   F R E E D O M
 WHITE RUSSIAN  ------------------------------------
  * 2 oz Vodka   Mix the Vodka and Kahlua together
  * 1 oz Kahlua  over ice, then float the cream or
  * 1/2oz cream  milk on the top.
 ---------------------------------------------------
root@OpenWrt:~#

The first thing (after having logged in) that you should do right away is to turn boot_wait on. This is important since if you ever screw up in the future (as in, can’t log in), you can always reflash the firmware using the TFTP method. Otherwise, you may end up with a bricked router.

To do this, run at the command line:

nvram set boot_wait=on
nvram commit

For more information on nvram, see the wiki.

Securing your new box

It is recommended that you set a password for your root account so random people can’t just take over your box (this should be obvious). You can do this with the passwd command.

After setting a new password, the OS will automatically install and enable the SSH server (dropbear). It will also disable telnet logins but, unfortunately, will keep the daemon running. You can free up some resources by doing the following:

killall telnetd
rm /etc/init.d/S50telnet

Next is to secure your wireless access points. If you already secured your WAP while it was running the Linksys firmware, then this step is done - unless your using WPA/WPA2 encryption, in which you have one step left (see below). If not, then you will have several settings you need to change. Since my access point was already locked down I didn’t have to do this step. However, I will do my best to guide you in case you didn’t.

nvram refers to the wireless adapter as wl0, so we can see all the available configuration options for this interface by doing the following:

nvram show | grep "wl0"

I won’t print the list here as there are quite a few options to change. To save you some time, if you need to get your access point working, make sure the following options are set:

#WPA mode
#ap = Access Point (master mode), sta = Client mode
wl0_mode=ap
 
#WPA SSID
wl0_ssid=wap
 
#WPA channel
#For North America: 1..11
wl0_channel=6 #channel access point is on
 
#WPA intrastructure
#0 = Ad Hoc mode, 1 = normal AP/Client mode
wl0_infra=1
 
#WPA broadcast SSID
#0 = on, 1 = off
wl0_closed=0

Note that you must commit any changes that are made to nvram before they can take effect. If you find your changes (after committing) don’t have any effect, you may need to reboot the router.

nvram set option=value    #example
nvram set option2=value2  #don't acually do
...
nvram commit

Anyways, back to security. If you would like to enable mac filtering:

#WPA MAC filter
#disabled = any MAC allowed, allow = only listed MACs allowed, deny = deny only listed MACs
wl0_macmode=allow
 
#WPA MAC filter list
#Space seperated list of MAC address to allow/deny
wl0_maclist="00:02:2D:08:E2:1D 00:03:3E:05:E1:1B"

The WRT54GL supports both WEP and WPA encryption. WPA is much stronger then WEP, and is highly recommended unless you need to provide legacy access to outdated equipment. If your going to use WEP, you should take other precautions such as MAC filtering. To enable WEP:

#WPA WEP encryption
#disabled = disable WEP, enabled = enable WEP
wl0_wep=enabled
 
#WPA WEP key number
#Selects which key (wl0_key[1-4]) to use for WEP encryption: 1..4
wl0_key=1
 
#WPA WEP key [1..4]
#WEP key in hexadecimal format (allowed hex chars are 0-9a-f)
#Don't use WEP keys with 00 at the end. 128 bit WEP key must be 26 hex digits long.
wl0_key1=supersecretkey1
wl0_key2=supersecretkey2
wl0_key3=supersecretkey3
wl0_key4=supersecretkey4

For the rest of us, here are the options needed to configure WPA:
Note that enabling WPA disables WEP.

#WAP WPA mode
# open = No WPA
# psk = WPA Personal/PSK (Preshared Key)
# wpa = WPA with a RADIUS server
# psk2 = WPA2 Personal/PSK
# wpa2 = WPA2 with RADIUS
# "psk psk2" = Both WPA and WPA2 Personal/PSK
# "wpa wpa2" = Both WPA and WPA2 with RADIUS
wl0_akm="psk psk2"
 
#WPA WAP encryption algorithm
#tkip = RC4 encryption, aes = AES encryption, "aes+tkip" = support both 
wl0_crypto="aes+tkip"
 
#WPA WAP preshared key
#Password to use with WPA/WPA2 PSK (at least 8, up to 63 chars)
wl0_wpa_psk=supersecretkey
 
#RADIUS server information
wl0_radius_key=
wl0_radius_ipaddr=
wl0_radius_port=

Note that WPA does not work with the default install, and requires you to install the NAS package before you can authenticate. You can easily do so by running:

ipkg install nas

Setting up neccessary services

Cron

There are a bunch of services you should likely setup before putting your router in production. One of those services is cron. There are two steps to setting up cron. First is to create the crontabs file in /etc/:

mkdir /etc/crontabs
touch /etc/crontabs/root
ln -sf /etc/crontabs/root /etc/crontab

The last two lines are for compatibility/habit sake as many Linux distributions typically keep cron information in /etc/crontab.

The other step is to have cron startup automatically on boot. You can do so by creating the file /etc/init.d/S60cron with:

#!/bin/sh
[ -d /etc/crontabs ] && crond -c /etc/crontabs

You can then start cron by running this script:

chmod 775 S60cron  #Make script executable, only need to do once
./S60cron

Date/Time

If you haven’t noticed yet, your router will not have its time set. One of the problems with the WRT54G line is that they do not have an internal clock, so they loose their time after resets. Furthermore, they are horrible for drifting. So, we will need to set their internal date/time on boot, and periodically (good thing we have cron).

Before we start though, we should set our timezone. You can do this by writing a timezone identifier to /etc/TZ. For example, for me, I did:

echo "MST7MDT" > /etc/TZ

You can find out more information on the TZ file here.

Now, to set time on bootup, add the file /etc/init.d/S42rdate with the following:

#!/bin/sh
/usr/sbin/rdate 192.43.244.18  #time.nist.gov

To keep your clock up-to-date, add the following line to /etc/crontab:

0 * * * * /etc/init.d/S42rdate  #syncs every hour

Dnsmasq

One of the things you should check on before getting too comfortable with your setup is to look at Dnsmasq, “a lightweight, easy to configure DNS forwarder and DHCP server.” There was not much I had to change here, but you should be familiar with it incase you want to have control of your DHCP assignments. For example, you can see in this file that you can control static DHCP assignments by adding entries into /etc/ethers. You can find more information on dnsmasq here, and an example configuration script here.

This will likely be the first file that you have run into that is read-only as it is a symbolic link to the file in the rom. If you want to edit this file (or any other default file), simply run something like:

rm dnsmasq.conf
cp /rom/etc/dnsmasq.conf /etc/dnsmasq.conf

Firewall

I could spend all day telling you about how to setup OpenWRT to be the be-all, end-all of all routers. However, I have completed the goal of this article by describing how to install OpenWRT, and how to configure some basic essentials.

One of the things you should look at before forgetting your router password is setting up the firewall rules. I’m not going to go into details on this, but OpenWRT uses iptables for its firewall rules. You could either configure it using iptables by editing /etc/firewall.user, or install something like Shorewall and use its easier to define scripting language.

Update: I have written an article on how to setup a firewall using Shorewall on the WRT54GL, including other advanced topics such as customizing the internal switch and traffic shaping.

You should also be familiar with how the WRT54GL’s hardware maps to the network interfaces. You can see from this picture how things are wired, and is a good blueprint to keep around.

Conclusion

Well, hopefully this article helps and your roqing with your new connection hub. If you liked this article (or found some errors), please report them in the comments below. ‘night!

Changing Permalink Structure

My initial permalink structure for posts was structured as such:
http://garycourt.com/blog/post/13

The problem with this structure is that just by looking at the URL, you are unable to determine what the content is about. A more common approach to permalinks (by other blogs) is to have the title in the URL, which I decided on, like so:
http://garycourt.com/blog/post/changing-permalink-structure-in-wordpress/

Now, luckily for me, it is fairly simple for me to make this change while maintain backwards compatibility with the old permalink structure. How? Well, the only difference is that the old URL always ended in a number, while the new URL always ends in characters. We can write rules that will be able to easily determine the difference.

WordPress keeps it’s URL structure rules in .htaccess, in the root of the WordPress directory. The rewrite rules are written using Apache’s mod_rewrite.

First, to maintain backwards compatibility with the old permalink structure, I copied the old URL rewrite code that finds blog posts. I then pasted this code, with some modification, above WordPress’s URL rewrite code.

# Begin Old Permalinks
<ifmodule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [S=6]
RewriteRule ^blog/post/([0-9]{4})/?.*$ - [S=5]  #Prevent breaking of year view
RewriteRule ^blog/post/([0-9]+)/trackback/?$ /index.php?p=$1&tb=1 [QSA,L]
RewriteRule ^blog/post/([0-9]+)/feed/(feed|rdf|rss|rss2|atom)/?$ /index.php?p=$1&feed=$2 [QSA,L]
RewriteRule ^blog/post/([0-9]+)/(feed|rdf|rss|rss2|atom)/?$ /index.php?p=$1&feed=$2 [QSA,L]
RewriteRule ^blog/post/([0-9]+)/page/?([0-9]{1,})/?$ /index.php?p=$1&paged=$2 [QSA,L]
RewriteRule ^blog/post/([0-9]+)(/[0-9]+)?/?$ /index.php?p=$1&page=$2 [QSA,L]
</ifmodule>
# End Old Permalinks

If your wondering what I changed, I added the first 6 lines (which I copied from the beginning of the WordPress’s rules, and added the seventh line to prevent breaking of year view (since this rule must always come before post view rules).

I then went into WordPress and changed the permalink structure from:

/blog/post/%postid%

to:

/blog/post/%postname%/

Now, by going to either permalink structure, they will get the same post.

Forcing New Permalink Structure

Ideally, we want all users using the old permalink structure to update their links to the new structure. The HTTP protocol has a response code for that purpose: 301 Moved Permanently. This redirect response will send back a new URL which the content being requested can now permanently be found at.

I found a really nice WordPress plugin that does this extremely easily: Permalink Redirect. Essentially this plugin will check the requested URL against a post’s permalink, and if they don’t match, sends a 301 Moved Permanently response for the new permalink URL. All you have to do is install the plugin, and your done!

Conclusion

There are many ways of changing your permalink structure without breaking pre-existing links, and this is just one way. Note, however, that all target permalink structures may not be possible. I got lucky and was able to change my structure effortlessly.

A plugin framework is nothing new, as there have been many great minds who have worked on the subject, so I shouldn’t have to reinvent the wheel. I started my search with the well known Eclipse. After delving into the development docs, I found that Eclipse 3 is built on top of the OSGi framework and JPF. So, delving in further, I read the spec on the OSGi framework and, after much thought, I believe it is possible to implement this framework in PHP and, at the same time, break new ground in PHP development by adding features that have never been done before (in PHP).

Goals

Some of the initial goals I had for a proper framework were:

• Universal
• Easy portablility of exisiting code
• Allows plugins lots of power, but in a controllable way
• Plugins should not have to be aware of other plugins it does not deal with
• Fast
• Dynamic

The OSGi framework is a universal framework that allows for dynamic loading and unloading of code. It allows for the easy portability of existing code, and uses namespaces such that there are no name or resource collisions. Each plugin (bundle) has lots of power and flexability (providing a service offers it), but it is all controlled through the framework using services. The OSGi framework does have overhead, and can be quite slow when starting up, but if we can minimize the number of times the framework is started (cacheing, or keeping it running), then the only slow down is the advantages we get from using the framework.

Initial Problems

One of the problems with the OSGi framework, if you start reading it, is that it is designed for Java, and is based on a lot of high-level Java functions. Essentially they are three things that OSGi needs that Java has but PHP does not:

• Class loading
• Namespaces
• Advanced security

The first one (class loading) is not much of an issue since we can import files that have class definitions in them. But what we can not do (easily) is enforce that only class definitions are loaded. Nor should we, as it breaks the very essence of PHP itself. However, we need to keep this in mind as we are implementing the framework for possible pitfalls (and security risks).

The second problem, namespaces, is a very tricky one. One of the original goals of the OSGi framework is to load (or unload) bundles of code such that it does not affect other bundles unexpectedly. (Bundles should not need to be aware of other bundles) Unfortunately when PHP5 was designed, they ended up cutting out namespace support. So what are we left with? Creating separate processes for each bundle isn’t the best answer since it will consume resources like mad, and sharing data would be a pain. However, threads uses very little additional memory, and allows for inter-thread communication easier. Now, unfortunately PHP does not have native thread support, but PECL’s runkit package supports sandboxed threads, and should be perfect for what we need to emulate the way Java implements namespaces. The sandboxing would also allow us to load code into each box without fear of it causing a collision in the main namespace. Also, runkit doesn’t completely isolate each thread from each other, as it provides mechanisms to communicate with the parent. Therefore, when we want to create a new namespace, we create a sandbox thread, initialize it with the environment we want, add functions that allow it to talk with other namespaces, and then load the user code.

The other solution, as I have recently become aware, would be to use the supposed namespace patch for PHP. However, there is apparently some big problems with it and is likely not the best route to take until they are fixed and further integration is done.

Lastly, PHP5 is sorely lacking security features. Sure there is safe mode, but its an all on/off solution and doesn’t allow for the fine grained control that the Java 2 Security Architecture provides (which is optionally required by the OSGi framework). However, I believe that Java’s Security Architecture can be mimicked in PHP5 by using PECL’s intercept package (doc), debug_backtrace(), and code signing. Essentially, before loading any user code, we setup the environment such that we intercept any potentially dangerous system functions and, when called, code will check to see if the calling code (debug_backtrace()) has permission (using code signing) to run the requested function.

Having identified and potentially eliminating the three biggest challenges, one problem remains - the user is required to install/patch at least two extensions to their PHP runtime engine. This is a problem because a) the user might not be able to because they are not admin or are using a pre-compiled package, or b) may conflict with other installed extensions. This problem could be simplified by writing a custom extension for the framework that implements all the desired features needed. But, unfortunately, there is no solution to this problem and is a consequence of using the framework.

Layers

The OSGi framework is defined as a layered structure. We too can also use this structure and add some other layers we need to setup PHP for the framework. The layers for this framework are listed below in an inverted order (bottom to top) and each layer’s code is able to access any other layers functions below it (providing it has the necessary permissions).

PHP5 w/ Extensions

This is a layer that we don’t necessarily need to do anything about. Its listed to hear to identify that PHP5 is required (for its class model, exceptions, etc.). The necessary extensions (runkit and intercept) should also be apart of this layer since they need to be compiled into PHP5 to improve the language enough so that we can do what we need to do.

PHP Environment Control

This layer is a required, simple abstraction layer/class for the compiled in extensions. It provides a standard API for easily accessing the necessary tasks that need to be performed with the compiled extensions.

The purpose of this layer is to abstract the implementation details of the required extensions such that we could potentially use any extension that performed similar tasks (or new language constructs in PHP6), and all we would have to do is modify the abstraction layer. Also, in the future, if a custom extension is written for this framework, it would have this API.

PHP5 Standardized API

This is a completely optional layer, but could bring some structure and help enforce good class-based API design. Essentially, this layer would implement the Java library in PHP. We would not, however, remove existing functions, but duplicate their functionality into a standardized API.

For example:

include('php/language/String');
 
$comment = new String('This is a coment');
$comment.replace('coment', 'comment');
 
echo $comment;

There has already been some work on this done with the Japha project as it has implemented the most important parts of the Java Standard API already. However, some modification would be required such that we can now actually implement class (code) loading/namespaces.

PHP5 Security Architecture

This is an optional layer that allows for the locking down of the environment such that untrusted code is allowed to safely execute without fear of causing damage to the system.

This is done by essentially mimicking the Java 2 Security Architecture. Before any user code is loaded, we have a list of all known dangerous system functions, and the required permissions needed in order to access them. Then a parser runs through this list and adds intercepts (using PECL’s intercept package) to each dangerous function. The intercept, when fired, will check if the calling function (look at the stack with debug_backtrace()) has the necessary permissions (using code signing and policies, discussed later) to run the requested function. If it does not, an exception is thrown.

The Java 2 Security Architecture does a good job defining how policies and code signing should work, so I won’t go into detail. But, an authority would need to be established in order to issue these certificates/policies in order for them to be enforceable.

OSGi Security Layer

The OSGi Security Layer is an optional layer that underlies the OSGi Service Platform. The layer is based on the Java 2 security architecture. It provides the infrastructure to deploy and manage applications that must run in finegrained controlled environments.

Essentially, this layer adds extra security features to enhance Java’s own in order to take account the fact that there are code bundles now. When reading this doc, you will notice that it mentions about digital signed jar files a lot. Now, we could either use the PAR Loader to implement this feature, or else we could just have digital signed directories of code that’s optionally installed using PEAR.

OSGi Module Layer

The standard Java platform provides only limited support for packaging, deploying, and validating Java-based applications and components. Because of this, many Java-based projects […] have resorted to creating custom module-oriented layers with specialized class loaders for packaging, deploying, and validating applications and components. The OSGi Framework provides a generic and standardized solution for Java modularization.

This layer defines Bundles, how they are defined and how they work. I won’t go into much detail here since the specification does a great job at it already. Just replace the words “Java” with “PHP”, and its pretty easy to understand and create.

OSGi Life Cycle Layer

The Life Cycle Layer provides an API to control the security and life cycle operations of bundles. […] The Module Layer does not define how a bundle is installed, updated, and uninstalled. [The installation of a bundle can only be performed by another bundle.] These life cycle operations are defined here.

Without going into too much detail, this section defined the API that controls the basics of Bundle control. It also what happens when the framework is started/shutdown.

OSGi Service Layer

The OSGi Service Layer defines a dynamic collaborative model that is highly integrated with the Life Cycle Layer. The service model is a publish, find and bind model. A service is a normal Java object that is registered under one or more Java interfaces with the service registry. Bundles can register services, search for them, or receive notifications when their registration state changes.

This is where our platform gets useful. The OSGi framework is built around services, each bundle having 0 to many services available, which are registered with the service registry defined in this layer.

Services

This layer is what adds the actual value to the framework and its purpose. Although any service could be defined depending the purpose of the application being written, the OSGi framework defines several universal/common services that should be implemented.

OSGi Package Admin Service

Bundles can export packages to other bundles. This exporting creates a dependency between the bundle exporting a package and the bundle using the package. When the exporting bundle is uninstalled or updated, a decision must be taken regarding any shared packages.

The Package Admin service provides an interface to let the Management Agent make this decision.

OSGi Start Level Service

This specification describes how to enable a Management Agent to control the relative starting and stopping order of bundles in an OSGi Service Platform.

The Start Level service assigns each bundle a start level. The Management Agent can modify the start levels for bundles and set the active start level of the Framework, which will start and stop the appropriate bundles. Only bundles that have a start level less or equal to this active start level must be active.

The purpose of the Start Level service is to allow the Management Agent to control, in detail, what bundles will be started and stopped and when this occurs.

OSGi Conditional Permission Admin Service

A key aspect of this security management API is the real time management of the permissions. This enables management applications to control the permissions of other applications with immediate effect; no restart is required.

OSGi Permission Admin Service

In the Framework, a bundle can have a single set of permissions. These permissions are used to verify that a bundle is authorized to execute privileged code. For example, a FilePermission defines what files can be used and in what way.

The policy of providing the permissions to the bundle should be delegated to a Management Agent. For this reason, the Framework provides the Permission Admin service so that a Management Agent can administrate the permissions of a bundle and provide defaults for all bundles.

OSGi URL Handlers Service

This specification is necessary because the standard Java mechanisms for extending the URL class with new schemes and different content types is not compatible with the dynamic aspects of an OSGi Service Platform. The registration of a new scheme or content type is a one time only action in Java, and once registered, a scheme or content type can never be revoked. This singleton approach to registration makes the provided mechanism impossible to use by different, independent bundles. Therefore, it is necessary for OSGi Framework implementations to hide this mechanism and provide an alternative mechanism that can be used.

OSGi Log Service

The Log Service provides a general purpose message logger for the OSGi Service Platform. It consists of two services, one for logging information and another for retrieving current or previously recorded log information.

OSGi Http Service

An OSGi Service Platform normally provides users with access to services on the Internet and other networks. This access allows users to remotely retrieve information from, and send control to, services in an OSGi Service Platform using a standard web browser.

I think this service could be the money maker for this framework. Essentially, you could create this service by modifying Nanoweb to work as the HTTP server, then you could run this framework standalone (without Apache) and get an increase in PHP performance and control.

OSGi Configuration Admin Service

The Configuration Admin service is an important aspect of the deployment of an OSGi Service Platform. It allows an Operator to set the configuration information of deployed bundles.

Configuration is the process of defining the configuration data of bundles and assuring that those bundles receive that data when they are active in the OSGi Service Platform.

OSGi Preferences Service

Many bundles need to save some data persistently–in other words, the data is required to survive the stopping and restarting of the bundle, Framework and OSGi Service Platform. In some cases, the data is specific to a particular user. Some data is not specific to a user, which we call system data.

OSGi User Admin Service

OSGi Service Platforms are often used in places where end users initiate actions. These kinds of actions inevitably create a need for authenticating the initiator. Authenticating can be done in many different ways, including with passwords, one-time token cards, bio-metrics, and certificates. Once the initiator is authenticated, it is necessary to verify that this principal is authorized to perform the requested action. This authorization can only be decided by the operator of the OSGi environment, and thus requires administration. The User Admin service provides this type of functionality.

Another important feature of this framework as it allows for a single, powerful, and standardized authentication system for the framework across multiple different application.

OSGi Event Admin Service

The Event Admin service provides an inter-bundle communication mechanism. It is based on a event publish and subscribe model, popular in many message based systems.

OSGi Service Tracker Service

The specification defines a utility class, ServiceTracker, that makes tracking the registration, modification, and unregistration of services much easier. A ServiceTracker class can be customized by implementing the interface or by sub-classing the ServiceTracker class.

OSGi Declarative Services

This service is a bit complicated in its definition, but basically provides a method of adding services that do not have to worry about services it depends on being active, and will only cause the framework to only load services when needed (reducing footprint and startup time).

There are various other services that the OSGi specification specifies. The ones not listed here are not likely needed for a PHP environment. (Unless say it was the only application running on a dedicated hardware device)

Usage

This is how I envision the framework being use; The application using the framework is designed to be run standalone and runs like a daemon process. At startup, it loads all the neccessary services (including the HTTP service) and then the application service. The application service controls a blog that is displayed (and receives feedback) from the HTTP Service. It also provides an admin interface for allowing the loading of plugins. These plugins are loaded/unloaded/updated at runtime and the framework never has to shutdown. Because the PHP code is loaded into memory and stays, the running of PHP code is fast and results come back quick.

Conclusion

Although a framework like this would be a tremendous undertaking (not including any applications built on top of it), I believe that this would get a lot of media attention and cause several preexisiting apps to be ported to the framework and, consequently, allow for the easy mashup of various services. And why not? Most pre-exisiting applications would only require a manifest and class loader file, and they could be run by the application without worry of namespace collisions. This could also breathe some new life into PHP development.

Now, having said all of this, none of this has been tested. This is purely a concept idea and may actually not be possible. My biggest concerns are, in fact, the two required extensions and if they can be loaded together and are able to perform a good enough job for what is needed. Having said that, a custom extension could (and eventually should) be written to handle the necessary limitations of PHP.

Now, I know a lot of people oppose the whole “PHP should not try to be like Java” bit, but Java has some really nice features, and combining those with PHP’s really nice features, we could create something better then the both of them. Just my opinion on it.

If anyone is interested in working on a framework like this, please feel free to contact me or leave a message in the comments.

Install AWStats

Start off by installing the AWStats package using APT.

apt-get install awstats

After installation, everything you need for AWStats can be found in the following directories:

/etc/awstats/

Configuration files for AWStats.

/usr/share/awstats/

Runtime libraries, plugins, language files, and icons.

/usr/share/doc/awstats/

README on how to setup AWStats. Consult if you are having problems.

/usr/share/doc/awstats/examples/

Setup and configuration scripts. If your looking for a script mentioned in the official docs, chances are it is here.

/usr/lib/cgi-bin/

Contains awstats.pl, the program itself.

Setup Apache

First thing that needs to be done is to setup Apache’s logging appropriately. I use Apache 2 on my server, so this article will be focused towards it.

Ensure that Apache is in fact logging access requests. For each virtual host (found in /etc/apache2/sites-enabled/), make sure there is something like the following present: (replace example.com with the virtual host domain name)

CustomLog /var/log/apache2/access.example.com.log combined

You can also check the main configuration file (/etc/apache2/apache2.conf) to see if a global CustomLog is specified, however, it is recommended that you create a log for each individual domain name. In any case, make sure that the last parameter of CustomLog is combined as it will help AWStats produce better results. (Note: that if you already have a CustomLog directive in your configuration file that uses something else other then combined, please delete the already pre-existing log files.)

Before we are done, copy /usr/share/doc/awstats/examples/apache.conf to /etc/apache2/conf.d/awstats.conf. This will setup the necessary aliases to access AWStats from the web (on all virtual hosts). If you would like to control which virtual hosts will have these aliases specified, then copy the code within apache.conf into a virtual host definition:

# This provides worldwide access to everything below the directory
<directory /var/lib/awstats>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
</directory>
 
# This provides worldwide access to everything below the directory
<directory /usr/share/awstats/icon>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
</directory>
 
# This provides worldwide access to everything in the directory
Alias /awstats-icon/ /usr/share/awstats/icon/
 
# This (hopefully) enables _all_ CGI scripts in the default directory
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

Don’t forget to restart Apache when your done:

/etc/init.d/apache2 restart

Setup AWStats

Next step is to setup the AWStats configuration files. In /etc/awstats/, you will see the file awstats.conf. It is recommended that you setup a configuration file for each virtual host that you want to monitor. To do this, copy awstats.conf to awstats.example.com.conf. (Replacing example.com with your domain name.) Next, go through awstats.example.com.conf and customize it for your site. The critical options to change are:

#Log file for virtual domain
LogFile="/var/log/apache2/access.example.com.log"
 
#Log type: Web
LogType=W
 
#Apache or Lotus Notes/Domino native combined log format (NCSA combined/XLF/ELF log format)
LogFormat=1
 
#Main domain name used to reach website. Used for log parsing (skipping) and server-side link generation.
SiteDomain="example.com"
 
#Other domain names that can be used to access web site. This example uses a regular expression to reduce typing.
HostAliases="REGEX[(www\.)?example\.(com|net|org)$]"

Testing

We can now generate statistics for your website by running AWStats:

/usr/lib/cgi-bin/awstats.pl -config=example.com -update

Which should output something like:

Update for config "/etc/awstats/awstats.example.com.conf"
With data in log file "/var/log/apache2/access.example.com.log"...
Phase 1 : First bypass old records, searching new record...
Parsed lines in file: 5
 Found 0 dropped records,
 Found 0 corrupted records,
 Found 0 old records,
 Found 5 new qualified records.

Providing there are no errors, we can view the results by pointing our web browser to:

http://example.com/cgi-bin/awstats.pl?config=example.com

Automation

At the moment, statistics will only be generated when you run the script manually. Therefore, lets automate it as a cron job. In /etc/cron.d/ there will already be a file called awstats. Theoretically you should be able to edit this file and change the part -config=, but I couldn’t get this to work. So, I wrote my own which I find works for me. If you’d like to do the same, replace the content of awstats with:

0 * * * * www-data /usr/lib/cgi-bin/awstats.pl -config=example.com -update >/dev/null

This code will cause your statistics to be generated every hour.

Now, there’s one small problem with this. For anyone familiar with Apache, you know that, by default, the Apache logs are rotated (to prevent them from getting to big) . This causes a problem that if entries to the logs are made between awstats running and the logs rotated, those entries are lost. Therefore, we need to modify /etc/logrotate.d/apache2, and add some prerotate code:

/var/log/apache2/*.log {
        weekly
        missingok
        rotate 52
        compress
        delaycompress
        notifempty
        create 644 root adm
        sharedscripts
        prerotate
                /usr/lib/cgi-bin/awstats.pl -config=example.com -update
        endscript
        postrotate
                if [ -f /var/run/apache2.pid ]; then
                        /etc/init.d/apache2 restart > /dev/null
                fi
        endscript
}

The changes I have made are:

• Added the prerotate section:

  prerotate
          /usr/lib/cgi-bin/awstats.pl -config=example.com -update
  endscript
  

• Changed the permissions on the log files:

  create 644 root adm
  

Note that the permission change is to allow the cron job (running as user www-data) to access the log files. (This is the lazy way) If you already have pre-existing log files, you can change their permission by running:

chmod o+r /var/log/apache2/*.log

If you don’t want to allow all users read access to the log files, then you can try changing the group owner on the log files to www-data. (I haven’t tried this, so no guarantee it will work)

Conclusion

There we have it, getting AWStats to run on Debian. One of the things I would recommend, before leaving this, is to secure the the generated results with a username and password (using Apache’s mod_auth). Although it is out of the scope of this article, if you would like me to go about showing you, please mention in the comments.

For more information on AWStats configuration options and abilities, please see their official documentation.

//Find the latest Gallery pictures
$gc_item_limit = 4;  //number of items to display
$gc_connection = mysql_connect(DB_HOST,DB_USER,DB_PASSWORD) or die("Can't connect to DB Server.<br />".mysql_error());
$gc_dbconnection = mysql_select_db(DB_NAME, $gc_connection) or die("Can't connect to DB.<br />".mysql_error());
$gc_run = 'SELECT g_id FROM g2_Item WHERE g_canContainChildren = 0 ORDER BY g_id DESC LIMIT '.$gc_item_limit;
$gc_result = mysql_query($gc_run);
if (mysql_num_rows($gc_result) < 1)
  echo '<p>No Pictures Found< /p>';
while ($row = mysql_fetch_array($gc_result, MYSQL_ASSOC)) {
  $gc_imageblock = g2_imageblock($row['g_id'], 120);
  $gc_imageblock = str_replace('id="g2content"', '', $gc_imageblock);
  echo $gc_imageblock;
}
mysql_free_result($gc_result);

You can see this code in action on my index page.

The game is played by placing Poplars on the board one at a time. Each spot on the board can only hold a limited number of Poplars (determined by the number of adjacent spaces), and when that spot is filled, it will “pop” and spread the Poplars to the adjacent spaces. However, the consequence of “popping” a space is that it may cause a subsequent space to be full creating a chain reaction of multiple spaces “popping”.

The game can be played with two to four players, human or computer, on any sized board. There are 5 skills levels (including a training level), undo move feature, and quick tip (for those who are stuck).

This was one of my most interesting projects in university at the time as it exposed me to such new concepts as game development, C++, MFC, Windows development, GUI development, artificial intelligence design, and usability design. I received an A+ for the project and the course, and won the unofficial award of Best Game of the Class.

For more information on Poplars and how to play it, please see the included help file.

Download Poplars