Random Disconnected Diatribes of a p&p Documentation Engineer
I've been struggling with the meanings of words again this week. Partly it's because I'm not a native US-English speaker, and partly it's because I tend to make wild assumptions about the way that the major IT hardware companies view their customers. I suppose I could buy a US-English to Queen's English phrase book to solve the first issue; and take more notice of website product reviews to resolve the second...
So, starting this week with a diatribe, consider how you would implement the web page for managing a device that allows you to specify optional settings (note the word "optional" - it's relevant later on). Let's assume that the setting in question is an IP address, and you provide four text boxes - one for each of the IPv4 sections of the address. And assume that you have added some client-side widget that validates the entries in each box and forces them to be a number between 0 and 255. All make sense so far?
Now remember the key word in this scenario: "optional". What happens when your users realize they made a mistake and want to remove the IP address? If you own a one of those routers that provide "a platform that is ready for service" (such as the 527W), what happens is that you can't. It seems like you are stuck with them for eternity (or until you toss the thing against the wall in frustration). You can't delete them. If you disable scripting and Java stuff the page doesn’t work at all. And, before you ask, the most recent firmware upgrade doesn’t fix it - in fact it doesn't even mention it in the "Known Issues" document. Neither is there a mention of it anywhere I can find searching the web. Obviously I'm the only person in the world who has ever tried to do this.
Ah, but when you go to the router's support site you get a nice pop-up Chat box so you can ask your question. And their answer? Here's an abridged version: "To get support from us you need a support contract. If you had purchased it from one of our partners you could get advice from them, but as it was purchased from Amazon there is no support unless you take out a support contract. Unfortunately you have chosen to buy from a grey market." I wonder if Amazon knows that they are a "grey market". And who would buy a support contract for a router than costs less than $200 ?
Anyway, after I finally decided to do a full reset and completely reconfigure it (there was no wall nearby to throw it at) I discovered that setting the optional DNS entries to 0.0.0.0 means that the router will just ignore them. All I can say is that it would have been nice to see this mentioned in the manual...
But I guess I should get to the original point of this post and mention my "US-English" problem. In between the tasks of my day job I've been creating some exercises that describe using Web Matrix to build a reasonably full-featured website for a soccer club. The topic of soccer wasn't my idea - it was part of the brief and I assume it's because soccer has a more universal international appeal than (American) football.
I realize that they call it "soccer" in the US to differentiate it from their version of "football" where you actually carry the ball around rather than kicking it - a bit like playing rugby in a suit of armour (or should I say "armor" - you can see how difficult this gets). What I didn’t realize is that in the US they have also changed all of the words associated with soccer. It's like it's been US-ized so that common soccer-related terms are made to sound like rude words.
The obvious example was the horror that spread across reviewers faces as they read about the fact that the players were trying out "a new team strip". I think they had visions of all the players running around naked. And when they came to the bit about "coping with a muddy pitch" they asked what the players were pitching for, or if I meant they picked the ball up and threw it. And when I talked about a "local derby", they asked if there were horses on the pitch as well...like it had morphed into some strange kind of polo match.
Likewise, when a news item on the site revealed that they were moving to a new clubhouse "due to a local road improvement scheme", I was told that something is a "scheme" only when there is nefarious or illegal activity going on. And that the list showing upcoming "fixtures" sounded like it should be full of things you nail on a wall or screw to the floor.
I wonder if it's time we took a stand and against all this. Though that probably reads like I want somewhere for the spectators to congregate to watch the match. Even though, in a "stand", you actually sit down. Oh well, I suppose it's all our (Queen's-English) fault really...
Sometimes I stop and wonder if I'm having one of those "more-senile-than-usual" moments. Did I click the wrong button, or have I forgotten to set some weird option before I started the process that looks like it will still be running when I get up tomorrow morning? What on earth am I trying to do that is so complicated a 2.27 GHz Quad Core Xeon E5520 running 64-bit Windows 7 can't achieve while I'm still awake?
So why not try it for yourself? Open Windows Explorer, select drive C: in the folder tree, and type the full name and extension of some file you know exists into the Search box at the top right of the window. A good one to try, if you have Microsoft Office installed, is Default.dotx. Then wait. Or go to bed. On my machine it was still searching after 10 minutes and hadn't found it yet. Now open your C:\Program Files (x86)\Microsoft Office\Office14\1033\QuickStyles folder (or some similar path depending on the version of Office you have installed). Gosh - there's a file named Default.dotx. But would you know to look there?
Where all this started was looking for a specific template file we use here at p&p. I know the file name - but after watching the pulsating green crawly thing in the address bar on my machine for more than 20 minutes, with the search still running and no sign it found the file, I opened another instance of Windows Explorer and started to look in the folders where I thought it would be. Needless to say, it wasn't. Not even in the elusive QuickStyles folder. Maybe I should just reinstall the tools that the template is part of with logging enabled on the MSI, and then read the log file to see where it gets put? Not exactly an interactive approach to searching...
In fact, the interactive approach I took was to write a simple search utility in VS 2010 to search all files and subfolders starting at a specified folder for a specific file based on the full name or a standard partial-match search string (such as "*.dotx" or "myfile?.*"). I actually got it finished and working before the search had finished. It found the file I wanted in the C:\Users\[me]\AppData\Roaming\Microsoft\Templates\ folder in 12 seconds. And the time taken to search all of 40 GB of files on drive C: was less than 30 seconds.
Yes, I know the Windows 7 search is doing clever stuff like looking inside files and looking at metadata. And I know you can change the options from the Organize menu in Windows Explorer (though it seemed to make little difference). And I know I should better organize where I put files that I want to be able to find again. OK, so Windows 7 does seem to be more predictable when searching than Vista was (see Having A Bad Where? Day). But, sometimes, all you need is to find a file that you know is in there somewhere...
Is it really possible to love jQuery? It certainly seems like it is from the numerous blog and forum posts I've read while trying to figure out how to make it do some fairly simple things. Many of the posts end with rather disturbing terms of endearment: "...this is why I just love jQuery" being a typical example. Yet I'm still not sure that our first blind date will result in a lasting relationship.
Perhaps if you spend your life building websites that incorporate the now mandatory level of flashy UI, animations, and interactivity jQuery is pretty much a given. At least it means that paranoid people like me who have Java, ActiveX, and Flash disabled in their browser actually get to see something. I got fed up with the sites you used to see (or, in my case, not see) a while ago that were basically just a large Flash animation - invariably with the focus on appearance rather than containing any useful content. But disabling script is generally not an option these days.
Mind you, I'm now finding the same problem with sites that are just a single large Silverlight control; though - being a 'Softie - I guess I do tend to trust Silverlight rather more than other animation technologies. Well, marginally more - I'm still a paranoid neurotic. You know what they say: "Just because you're paranoid doesn't mean they aren't watching you."
There's plenty of API information, and plenty of blogs that provide just enough to not quite get things working. As an example, I'm using the load method to reload a partial section of a page into a div element, and I want to change the mouse pointer to a "wait" cursor and display an indeterminate "Please wait..." image while it loads. The docs say I can flip the cursor for the page using the css method of the element that holds the partial page content (though they don't mention that it doesn't work on hyperlinks within it). And that I can display my hidden div containing the loading image using the element's show method.
But, of course, figuring out this is the easy part. Simply calling the methods one after the other to change the mouse pointer, show the image, load the new content, hide the image, and change the mouse pointer back again doesn't work. Instead, you have to chain the method calls so that they only execute after the previous one has completed - mainly, of course, because the load method is asynchronous. The "getting started" docs hint at all this without actually using the dreaded "a" word; while the "real programmer" docs are full of barely comprehensible tips such as "CSS key changes are not executed within the queue."
Of course, these days, asynchronous programming is a common scenario, so I'm a bit surprised that the docs don't just bite the bullet and use the "a" word from the start. But I guess there's another issue as well: no programmer with any remaining shred of pride would use separate callback functions. You wouldn't dare let anyone see your code if it didn't use lambda expressions for callbacks - even if you are still a bit frightened by them. Let's face it, finding syntax errors and debugging statements that cover twenty lines and end with a dozen closing curly and round brackets is not a procedure designed to aid mental stability or promote a restful programming experience. Especially when the typical error message is just the amazingly useless phrase "Object expected". So maybe the documentation people want to avoid using the "l" word as well...
As in many households, several regular and occasional computer users take advantage of my connection to the outside world. I use ISA Server 2006 running as a virtual Hyper-V instance for firewalling and connection management (I'm not brave enough to upgrade to Forefront yet), and all incoming ports are firmly closed. But these days the risk of picking up some nasty infection is just as great from mistaken actions by users inside the network as from the proliferation of malware distributors outside.
Even when running under limited-permission Windows accounts and with reasonably strict security settings on the browsers, there is a chance that less informed users may allow a gremlin in. So I decided some while ago to implement additional security by blocking all access to known malware sites. I know that the web browser does this to some extent, but I figured that some additional layer of protection - plus logging and alerts in ISA - would be a useful precaution. So far it seems to have worked well, with thankfully only occasional warnings that a request was blocked (and mostly to an ad server site).
The problem is: where do you get a list of malware sites? After some searching, I found the Malware Domain Blocklist site. They publish malware site lists in a range of formats aimed at DNS server management and use in your hosts file. However, they also provide a simple text list of domains called JustDomains.txt that is easy to use in a proxy server or ISA. Blocking all web requests for the listed domains will provide some additional protection against ingress and the effects of malware that might inadvertently find its way into a machine otherwise; and you will see the blocked requests in your log files.
They don’t charge for the malware domain lists, but you decide to use them please do as I did and make a reasonable donation. Also be aware that malware that connects using an IP address instead of a domain name will not be blocked when you use just domain name lists.
To set it up in ISA 2006, you need the domain list file to be in the appropriate ISA-specific format. It's not available in this format, but a simple utility will convert it. You can download a free command line utility I threw together (the Visual Studio 2010 source project is included so you can check the code and recompile it yourself if you wish). It takes the text file containing the list of malware domain names and generates the required XML import file for ISA 2006 using a template. There's a sample supplied but you'll need to export your own configuration from the target node and edit that to create a suitable template for your system. You can also use a template to generate a file in any other format you might need.
To configure ISA open the Toolbox list, find the Domain Name Sets node, right-click, and select New Domain Name Set. Call it something like "Malware Domains". Click Add and add a dummy temporary domain name to it, then click OK. The dummy domain will be removed when you import the list of actual domain names. Then right-click on your new Malware Domains node, click Export Selected, and save the file as your template for this node. Edit it to insert the placeholders the utility requires to inject the domain names into it as described in the readme file and sample template provided.
After you generate your import file, right-click on your Malware Domains node, click Import to Selected, and locate the import file you just created from the list of domain names. Click Next, specify not to import server-specific information, and then click Finish. Open your Malware Domain set from the Toolbox and you should see the list of several thousand domain names.
Now you can configure a firewall rule for the new domain name set. Right-click the Firewall Policy node in the main ISA tree view and click New Rule. Call it something recognizable such as "Malware Domains". In the Action tab select Deny and turn on the Log requests matching this rule option. In the Protocols tab, select All outbound traffic. In the From tab, click Add and add all of your local and internal networks. In the To tab click Add and add your Malware Domains domain name set. In the Content Types tab, select All content types. In the Users tab select All users, and in the Schedule tab select Always. Then click OK, click Apply in the main ISA window, and move the rule to the top of the list of rules.
You can test your new rule by temporarily adding a dummy domain to the Domain Name Set list and trying to navigate to it. You should see the ISA server page indicating that the domain is blocked.
If you wish, you can create a list of IP addresses of malware domains and add this set to your blocking rule as well so that malware requests that use an IP address instead of a domain name are also blocked. The utility can resolve each of the domain names in the input list and create a file suitable for importing into a Computer Set in ISA 2006. The process for creating the Computer Set and the template is the same as for the Domain Name Set, except you need to inject the domain name and IP address of each item into your import file. Again, a sample template that demonstrates how is included, but you must create your own version as described above.
Be aware that some domains may resolve to internal or loopback addresses, which may affect operation of your network if blocked. The utility attempts to recognize these and remove them from the resolved IP address list, but use this feature with care and check the resolved IP addresses before applying a blocking rule.
Another issue is the time it takes to perform resolution of every domain name, and investigations undertaken here suggest that only about one third of them actually have a mapped IP address. You'll need to decide if it's worth the effort, but you can choose to have the utility cache resolved IP addresses to save time and bandwidth resolving them all again (though this can result in stale entries). If you do create a Computer Set, you simply add it to the list in the To tab of your blocking rule along with your Domain Name Set. Of course, you need to regularly update the lists in ISA, but this just involves downloading the new list, creating the import file(s), and importing them into your existing Domain Name Set and Computer Set nodes in ISA.