I've written a tutorial on how to install and configure the login plugin for Blosxom. This was originally written on 2003.11.16.

---

by: Douglas Nerad

Let's say in Blosxom you want to password protect various directories with different passwords. How to go about this? I'm writing this based on my experience, running on OS X server. It assumes you have Rael Dornfest's cookies plugin and Fletcher T. Penney's login plugin, that you've put them in your plugins directory (you will probably have to rename "cookies" to something like "9999cookies" to have it load early) and that your site still reloads without error. It also works best if you have the exclude plugin installed and working so the directory you want to protect doesn't have entries appearing on your primary page.

First, let's configure the login plugin. Open it in your favorite text editor. I use BBEdit, but you can use TextEdit or pico, or even vi; do NOT use MS Word. In the "configurable variables" section there is some documentation from Fletcher you should read through even if you don't understand it at first.

1.1: The first variable is the location of the password file we'll create:

my $passwd_file = "$blosxom::plugin_state_dir/login/password";

If you do not use Blosxom's plugin_state_dir be sure you put the full path to the file starting from the root. The file can reside anywhere on the server, preferably in a non-world readable directory such as /Library/Webserver/Data/foo/password. It should be a non-world readable directory because otherwise someone might be able to view it. On *nix systems you can put a period at the beginning of the file name to make the file invisible. I'm not making this one invisible for easier reference later.

1.2: The second variable is to set the location of the file you will use to set which users have access to which directories.

my $excludefile = "$blosxom::plugin_state_dir/login/requireuser";

This file can also be made invisible and should ideally not be in a world readable directory, either. Generally you'll want to set it to the same place you want to put the password file.

1.3: The third sets the message users will see when they goto your site.

my $default_message = "Please log in.";

1.4: The last variable is used if you would like people to request usernames and passwords from you. It requires that you look at the file it creates to see if anyone has asked to be added.

my $pending_file = "$blosxom::plugin_state_dir/pendingaccounts";

Personally I don't use this feature as anyone who needs to see my private stuff can ask me personally if I haven't already given them access.

Save and close the login plugin. Now it's time to create those files.

2.1: Goto your plugins directory you've set up for Blosxom. Create a folder there called "login".

2.2: Creating the password file is the one time you will have to use the terminal/command line. Open a terminal and log onto the machine where Blosxom reside. Navigate to the login folder we created above (use cd to change directories). Once there type this on the command line and change the "username" to the name of a legitimate user:

htpasswd -c password username

This will create a password file called "password" in the directory you've navigated to (hopefully the login directory we created!).

2.3: Now let's create the "requireuser" file. This file is used to determine which directories the user is allowed to navigate into once logged on. Fletcher has provided a number of ways to set this file up, all documented within the plugin. Here is what he wrote:

the excludefile is built using regular expressions in the format:

user=page

user is a regexp to match allowed user (.* matches all VALIDATED users)
page is a regexp to match pages or directories (.* matches all pages)

Examples:

A blank or nonexistent file allows full access to anyone, logged in or not

myusername=.*
Only someone logged in as myusername can access any files on the web site

(myuser1|myuser2)=private
Only these two people can access a file or directory named private, private1, privatestuff, etc

.*=priv$
Any VALIDATED user can view the directory named priv, but this doesn't affect one named private

For now, since we only have one user, this might be how you set your "requireuser" file, changing "username" to the name of the user you created in 2.2 and assuming the directory you want to protect is called "private":

username=private

You can assign access to different directories on a line by line basis:

username1=private
username2=secret

Now it's time to add certain variables to your flavour files. Determine where you want the login fields to appear on your page, then open the flavour file that corresponds to that location. My login screen is in my head.html file.

3.1: Open your flavour file and add $login::message and $login::loginform to the html file. This is what mine looks like:

<span class="navi">
<b>authenticate</b>
<br>$login::message
$login::loginform
</span>

You can also add $login::signupform if you would like fields for people to request usernames and passwords. It will create a file you defined in step 1.4 and as I state there, I personally don't use it.

Now is the time to test your site. If you have followed the steps outlined here all should work fine. Load your site and you should see the login fields. Before entering the username and password, try going to the directory you want protected (for example http://www.your-site.org/private/). Could you see the articles there? If you couldn't then go back and fill in the user/pass and click login. Now goto the protected directory and you should see all the articles. Congratulations! Login is successfully installed and configured!

Of course Murphey's Law rules the universe so possibly the instructions didn't work out for you. Troubleshooting the login plugin can be confusing, but following a few basic things should clear things up.

4.1: Check that the locations of the files you created are truly in the directories you defined in steps 1.1 and 1.2; are the files are there? Double check that the names of the files are the same as you defined, too. A simple typo had me going a full day in utter frustration.

4.2: If you could see the files without logging in, check that the requireuser file you created in 2.3 is set up correctly without typos.

4.3: The cookies plugin needs to be working. You can check the logs if you have access to them. See if the webserver generated any errors regarding the cookies plugin. Alternatively in your browser you should be able to see all the cookies your browser has accepted, and yours should be on that list.

4.4: It is possible that your permissions are not set correctly. If you are on a *nix machine you can goto the directory that contains the password and require user files and type ls -l (or ls -al to also see invisible files). Your files should have "r" in three places, which means that the file is readable by pretty much everyone. If it doesn't you will have to change this.

-rw-r--r--   1 root    admin    37 Nov 14 19:38 password
-rw-r--r--   1 foo     staff    22 Nov 14 19:45 requireuser

You can type chmod +r [filename] to attempt to change the permissions to be readable. As a warning, do not get carried away with changing permissions as you could potentially screw something up. When in doubt, get help from someone who would know something about this. Hopefully my instructions don't mess things up, either; I am not a *nix master!

4.5: Finally, goto the Blosxom Mailing List and see if someone has had a similar problem (try a search for "login") and fixed it. You could also try searching on Google. If you cannot find anything at all, you could post a request for help on the mailing list.

The login plugin provides a degree of security, but should NOT be considered absolute. There haven't been any security holes found in the login plugin, but it hasn't been strenuously tested yet. If you are well and truly concerned about the content of your site, possibly the best advice possible would be to simply not post the content.

The easiest way to add more users to your burgeoning list is to repeat the htpasswd command into a new file, open that file in BBEdit (or your prefered text editor), copy the username and password (which will appear scrambled), and paste that into the "official" password file on the next line after your first username/password. It takes a few extra steps, but it will work.

That being said, I am very happy with my login installation, and I think you will be as well!