| Intranet/Hosting Toolkit | [table of contents] |
![[CFX_NFS]](../../ihtk/nfs/title.png) v1.6 December 2nd 2001 |
CFX_NFS
OPEN-SOURCE NT DLL for Cold Fusion 4.0.1 and up Lewis A. Sellers http://www.intrafoundation.com/ihtk.asp products@intrafoundation.com |
|
FOREWORD This is an Allaire Cold Fusion Extension Tag (CFX). It is for use with Allaire Cold Fusion Servers 4.0.1 (and up) running on Microsoft NT. It was written by Lewis A. Sellers of Intrafoundation Software. CFX_NFS allows you to manage shares, mapped network drives and NTFS file permissions (ACLs). This functionality, in combination with CFX_UserManager, allows you to create folders on shared or local drives they will allow or deny access depending on NT usernames and group memberships. Please read the version history for current tag status before emailing questions. |
C O N T E N T S |
The tag itself returns a couple variables back no matter what you do (NFSDescription, NFSVersion and NFSError). These are always available unless there is a catastrophic failure of the tag.
Additionally you can use the ABOUT function to return more detailed information on the tag. The fields returned are mostly only of interest for curiosity or in debugging a situation.
Note below that though the tag returns it's SerialNumber, it's not used currently, and hasn't been for a very long time, but probably will be again soon.
For the curious, it also proves the total number of lines of c/c++ that the current build was using. This includes the scant comments in the source code. For instance, this build of the tag has 3349 lines of code.
The quality field will be one of the following four: "Alpha", "Beta", "Gamma" or "Omega". Quality relates the quality control status of the version of the tag you're currently using.
Alpha code is highly unstable and shouldn't be trusted for anything. Do not use on production machines.
Beta code is close to being finish and it is in a debugging phase. Do not use on production machines.
Gamma code is for use on production machines. As far as the beta testers have determined it works as it should.
When a product goes Omega that generally means it is long used Gamma code that is now no longer being maintained.
New as of 2.0. Returns information about the server the cfx tag is installed on. For the most part these fields are of little practical use beyond curiosity. ComputerName and Username are exceptions however.
ComputerName relates the actual name given to the computer by netBIOS. This is also known as the server name if you prepend two-slashes to it. For instance, you're currently reading this on a machine that calls itself SASHA.
Username is the NT user name of the account that the ColdFusion application server is running under. It's installed by default to use SYSTEM. Some people will create an Administrator account specifically for ColdFusion to run under. You, btw, are using the account SYSTEM to run ColdFusion.
The fields returned are:
MaxUsernameLength, MaxPasswordLength and MaxPathLength are useful in that they give you the system's maximum character length for those three fields. This is information, which if you didn't already know of it, is useful in checking form fields for valid data.
This function returns a list of all servers in a domain. If you don't specify a domain, it assumes the local one.
This function returns a list of all domains.
This function returns a list of all network printers.
Retrieves the Primary (PDC) Domain Controller name. Of use mainly for NT4.
The function returns a SQL query with the following column:
Primarily of use under the MS IIS web server, this group of functions allows you to manage access to network shares, drive-mapped network shares and folder permissions (ACLs). (These functions were experimentally introduced as of versions 1.13 to 1.15, and officially as of 2.0.)
This functions returns a query containing detailed information about all the local drives on a machine. This, most importantly, includes their Format (FAT, NTFS, CDFS, etc) and the amount of space (in bytes) remaining on them. Note that all sizes are related in bytes and should be valid up to 2^63 (9,223,372,036,860,000,000) bytes.
Asks remote servers to return a list of their drives in the LETTER/COLON format. The CF server must be a member of the Administrators or Account Operators groups for this to return valid data.
Lists all shares on the machine.
This creates an alias to a drive:folder location that is shared by all applications on the network.
The PATH should (illogically) not end with a directory symbol (\). Drive:Path.
<CFX_NFS ACTION="SHAREADD" SHARENAME="name" PATH="drive:path" COMMENT="comment" USERS="n|0" QUERY="s">Removes the specified share.
<CFX_NFS ACTION="SHAREDELETE" SHARENAME="name">
Lists all network shares mapped to a local device/drive.
Maps an unused local drive letter to a network share. Optional parameters are Username, Password and ReconnectAtLogon.
If you use PASSWORD="" then there will be no password. If you do not use PASSWORD then the default system password will be used.
[There are currently some scope issues with NETWORKDRIVES and MAPNETWORKDRIVE that are being investigated. All other functions are, as far as is know, functioning correctly.]Disconnects a drive mapped from a network share.
<CFX_NFS ACTION="DISCONNECTNETWORKDRIVE" LOCALNAME="z:">Windows NT and Windows 2000 have a file system available called NTFS (NT File System). Unlike the FAT file systems of DOS, Windows 95 and Windows 98 it has a file security system integrated into it. The security system is based on NT user and group names and various permission types you wish to assign them for a file or folder.
The true inner workings of the NTFS ACL are rather bizzare, but for your purposes this has all been distilled and isolated into three (3) access types (ALLOW, DENY and REVOKE) and eight (8) permissions (RWXDPOCF).
When working with permissions you will name the user or group you are giving access to or denying from a file or folder. When created all files and folders have a few users or groups added to them by default, such as SYSTEM and Everyone. This is normal.
As a general rule you shouldn't delete or modify any of these unless you know what you're doing.
NOTE: Everyone is a special account name which simply signifies the permissions you grant to everyone else who you've not specifically named.
There are only three basic access types involved with file security: ALLOW, DENY or REVOKE. If you add an ALLOW access type to a file for a user you grant them certain permissions (see below) such as being able to read the file or list the contents of a directory.
When you add a DENY to a file for a user, say "mrsmith", then you deny specific permissions to this file to the account "mrsmith".
REVOKE simply deletes all ALLOW or DENY access types on the specified file for the user named. That is, it removes all reference to the user from the file, good or bad.
Permissions. In reality NT has a complicated tangle of permission masks and ACE structures, but we're not going to get into that. For our purposes there are only eight (8) permission types: RWXDPOCF. What they do varies slightly depending on whether we're talking about a file or a folder, but they are, more fully:
Allows viewing the file's data
For directories:Allows viewing the names of files and subdirectories
Allows changing the file's data
For directories:Allows adding files or subdirectories
Allows running the file if it is a program
For directories:Allows changing to subdirectories in the directory
Allows deleting the file
For directories:Allows deleting the directory
Allows changing the file's permissions
For directories:Allows changing the directory's permissions
Allows taking ownership of the file
For directories:Allows taking ownership of the directory
Under Windows NT folders, btw, are treated as any other file in many respects even though their permissions, as related above, have slightly different effects. The major difference with a folder you can specify the permissions that files created in that folder will inherit.
To add inherited permissions to a folder, simply use lowercased permission letters. That is: "rwxdpocf" instead of "RWXDPOCF". Note that inherited permissions are kept seperate from normal permissions. THIS is why when you do the PERMISSIONS function on a folder you will see double and triple entries for users. Some rows are for normal permissions. Others are for the inherited ones.
Permissions, btw, are valid only on NTFS file systems, which are an option under Windows NT and Windows 2000 only. You can not use any of this functionality on simple consumer-grade operating systems such as Windows 98.
Some of these functions may return the fields SID and AccessMask. You can safely just ignore these fields if you wish, but, for those of you who hardcore into managing your file permissions they can be very useful for working through the occasional difficult permissions problem that may come up. A SID, if you wish to know, is a Security Identifier. It's how windows actually uniquely identifies a user, etc across multiple domains. The AccessMask is the binary representation of the permissions codes (in this case, in hexidecimal).
As I said, you can completely ignore these fields. But if you need them they're there.
Lists permissions relating to a specific folder. Permissions (or ACL, ie Access Control Lists) is a somewhat complex thing under NT. In general however the purpose of permissions is to specific the name of a user or a group and what can of access they are to have to this folder.
Is is possible for a file to have permissions set for a user that no longer exists. In this case both username and domain will be blank.x
<CFX_NFS ACTION="PERMISSIONS" FOLDER="w:\user\lsellers" QUERY="lsellers">Similiar to PERMISSIONS, this allows to to specify the USERNAME and TYPE you are specifically looking for. It returns only records matching these.
TYPE can be of the strings: "Allow", "Deny" or "Any".
<CFX_NFS ACTION="SEARCHPERMISSIONS" FOLDER="w:\user\mrsmith\" USERNAME="mrsmith" TYPE="DENY">Grants access permissions to a specific user or group.
<CFX_NFS ACTION="PERMISSIONALLOW" FOLDER="w:\user\mrsmith" USERNAME="mrsmith" PERMISSION="RWXD">Denies access to the folder for a specific user or group.
<CFX_NFS ACTION="PERMISSIONDENY" FOLDER="w:\user\mrsmith\papers\" USERNAME="bob" PERMISSION="RX">Removes access or denial of access to the folder for a specific user or group.
<CFX_NFS ACTION="PERMISSIONREVOKE" FOLDER="w:\user\mrsmith\" USERNAME="exemployee">This function has little practical use except perhaps for debugging your ACL settings. It is similiar to PERMISSIONS but, unlike the predigested data that function returns, this gives you the rather raw low-level data. Most of it will probably be a complete mystery to you, but if you want to know what the permissions data REALLY looks like -- this is it.
The CACLS field, btw, synthesises all this raw data into a "CACLS" compatible text string (or tries -- it should be close). If you've been using the CACLS command line tool before hand, then this should make you feel right at home.
The query fields returned are:
![[The grassy field]](../../ihtk/nfs/bridge.png)
Upgraded CFX_GetUserGroups, CFX_UserManager and CFX_NFS from class-less C to C++.
To be honest I don't remember what changes I made for 1.4 it's been so long. It was something minor but I didn't make any notes of it at the time. I believe it was an amplification of something said in the tests to avoid confusion.
Completely rewrote all the function code except that relating to permissions. This way should be much better for large networks. Should have done it this way to begin with... but I didn't know then the MS internals that I know now.
Still having some difficulties with mapped network drives. There are currently some scope issues with NETWORKDRIVES and MAPNETWORKDRIVE that are being investigated. All other functions are, as far as is know, functioning correctly. Hope to have this resolved by the next release.
Added a few new functions, and since it's the holidays (vespucia's independance day) and no one's had a chance to really make production use of the v2 code yet, I changed some of the function fields. :) Head's up.
(I hate legacy code getting in the way of improvements or having the code become overly complex and more apt to unforseen failure. Moreso since this software is running on a couple different US Mil & Space Support sites. Don't want anything blowing up that's not supposed too.)
Oops. Forgot to clean up the NFS documentation and a few of the network drive functions. Sorry about that. Was in such a rush to get the thing out before the holiday weekend it slipped my mind. Should be fixed now.
I'll up the ums2.1 with nfs1.2 in a few days.
Some issues with deleted user accounts were addressed and the documentation cleaned up.
Sorry about the photos. When I have time I'll scan in more artist imagery.
All of the functionality of this tag comes from the 2.0betas of CFX_UserManager. It seemed logical to strip out all the newly written file-centric code and place it all in it's own tag. Anyone who has used the 2.0betas 1 through 5 will be immediately familiar with most of the functionality of the new tag. Some of the names and parameters have changed, but the essense is the same.