• Creating a file containing usernames and passwords.
• Telling the server what resources are to be protected and which users are allowed to access them.

Creating a User Database
By default, the Sambar Server uses the config/passwd file for user and group access permissions. The User Management system administration forms can be used to dynamically modify this file via a browser interface. If no User Database is specified, this is the mechanism that is used.

It may be desirable to provide an alternative list of users and passwords for user authentication. To accomodate this use, the Sambar Server supports the "standard" user:password file format used by NCSA and Apache. Important! The default encryption mechanism used by the Sambar Server is not compatible with crypt which is used on Apache UNIX servers (the -d flag can be passwd to htaccess to use Unix crypt; the config.ini parameter Use Unix Crypt must also be set to true if you wish to use UNIX encryption). By default, both the Sambar Server passwd server config.ini file should set the Use Unix Crypt file and htpasswd files use the encryption mechanism implemented by the sacrypt utility shipped with the Sambar Server.

The htpasswd file format consists of a list of usernames and passwords, with the username and password being separated by a colon. To be compatible with Apache and NCSA, an htpasswd program is provided for creating the user file and to add or modify users. At this time, DBM-type user authentication is not supported.

Using htpasswd
To create a new user database file and add the username "billy" with the password "bob" to the file C:\sambar\users

htpasswd -c C:\sambar\users billy

The -c argument tells htpasswd to create a new user file. When you run this command, you will be prompted to enter a password for billy and confirm it by entering it again. Other users can be added to the existing file in the same way, except the -c argument is not needed. The same command can also be used to modify the password of an existing user.

An optional -d argument tells htpasswd encrypt the passwords using the Unix crypt() functionality (allowing the file to be compatible with Apache Unix servers). To use this functionality, the server config.ini file should set the Use Unix Crypt parameter to true.

Important! For security reasons, the htpasswd file should not be placed under the documents directory.

Configuring the Sambar Server
The directives to create a protected area can be placed in a .htaccess file within the Sambar Server documents directory that should be restricted. The Sambar Server also supports the use of <Directory> and <Location> section directives like those found in the httpd.conf or access.conf files under Apache and NCSA. For system-wide security, the Sambar Server first looks for a config/htaccess file. Administrators can this "global" config/htaccess file to restrict access to any directory in the server and/or prevent users from over-riding security via per-directory .htaccess files. Important: For optimal performance, the AllowOverride none directive can be used in the config/htaccess file to eliminate per-directory lookups.

To restrict access to a directory using a .htaccess file, you must first ensure that the Sambar Server user authentication is enbled. The config/config.ini file parameter Enable .htaccess should be set to true. This parameter can be configured via the Server Configuration system administration forms.

To restrict a directory to any user listed in the users file (created in the preceeding section), you should create a .htaccess file containing:

AuthName      "Login to Secret Stuff"
AuthType      Basic
AuthUserFile  C:\sambar\users

require       valid-user

The following .htaccess example illustrates the most simple and straightforward access constraint used with the Sambar Server:

AuthName      "My Secret Stuff"
require       valid-user

This two line .htaccess file indicates that all content within and below this directory in which this file is located should only be available to "valid" Sambar Server users (users configured via the User Management section of the server administration forms).

The .htaccess constraints are hierarchical, meaning that a constraint higher in the directory tree can affect contents nested below. When multiple .htaccess files are found within a hierarchy, the rules enforced are generally a composite of all rules found, unless override of the constraints are not permitted. Sambar Server Pro users can view a report on the ultimate rules that apply to a given directory using the Document Manager forms found in the Administrative console.

IMPORTANT!An unknown or malformed directive will cause the server to stop processing the .htaccess file and deny access with an Internal Server Error. Not all NCSA/Apache directives and/or directive options are supported. The maximum length permitted for any single directive line is 1024 bytes.

The following specifies the directives presently supported by the Sambar Server:

Directive	Usage
<Directory path>	Specifies that the directives following this line should only be applied to requests beneth the physical path location (case insensitive), i.e. c:/docs/samples. The directives are terminated by the </Directory> directive. Important! If the path being specified contains spaces, it must be quoted; in addition, all directory separators are translated to forward slashes (/) rather than the traditional Windows backward slash (\).
<Location url-path>	Specifies that the directives following this line should only be applied to requests beneth the url-path location (case insensitive), i.e. /samples. The directives are terminated by the </Location> directive.
AllowOverride none	Specifies that no other .htaccess files can override the directives in this file. This directive has a performance benifit of allowing the server to stop traversing the hierarchy looking for .htaccess files.
AuthName	Specifies the realm name for this user authentication area. Once a user has entered a valid username and password, any other resources within the same realm name can be accessed with the same username and password. Note: Strings with spaces must be quoted.
AuthType	Specifies the protocol to be used for authorization. Presently, Basic is only method available from current browsers. The Sambar Server ignores this directive.
AuthUserFile	Tells the server the location of the user file created by htpasswd. If this directive is missing, the Sambar Server config/passwd file is the default. If the path provided does not include the "drive" (i.e. d:\sambar\users), the path is assumed to be relative to the Sambar Server configuration (config) directory.
AuthGroupFile	Tells the server the location of the groups file to used for authentication. If this directive is missing, the Sambar Server config/passwd file is the default. If the path provided does not include the "drive" (i.e. d:\sambar\users), the path is assumed to be relative to the Sambar Server configuration (config) directory. Note: A user can belong to at most 200 groups.
require valid-user	Specifies that any user found in the user database can access the the area.
require user user1 user2... userN	Specifies a space-separated list of users that can access the area. i.e. require user billy ray
require group group1 group2... groupN	Specifies a space-separated list of groups that can access the area. i.e. require group engineering marketing If both a require user and a require group are defined, any user in the listed groups, or any user listed explicitly can access the resource.
norequire from ip1 ip2... ipN	Specifies a list of IP addresses which a valid-user authorization is not required to access the area. This IP list over-rides the require directives. Wild-card pattern matching can be used within the IP addresses (i.e. * and []). Note: Only IP address may be specified unless DNS address resolution is turned on, in which case hostnames should be provided.
allow from all	Allow access from all hosts.
allow from ip1 ip2... ipN	Specifies a list of IP addresses which are allowed access to the area. Wild-card pattern matching can be used within the IP addresses (i.e. * and []). Note: Only IP address may be specified unless DNS address resolution is turned on, in which case hostnames should be provided. i.e. allow from 192.164.170.128 193.160.*
deny from all	Deny access from all hosts.
deny from ip1 ip2... ipN	Specifies a list of IP addresses which are denied access to the area. Wild-card pattern matching can be used within the IP addresses (i.e. * and []). Note: Only IP address may be specified unless DNS address resolution is turned on, in which case hostnames should be provided.
order deny,allow	Specifies that the deny directives are evaluated before the allow directives (the initial state is OK.)
order allow,deny	Specifies that the allow directives are evaluated before the deny directives (the initial state is FORBIDDEN.) Note: This is the default.
order mutual-failure	Specifies that only those hosts which appear on the allow list and do not appear on the deny list are granted access.
satisfy any	It is possible to restirct both by username (via require) and hostname (via allow) restrictions at the same time. The server will require that both restricts be satisfied unless the satisfy any directive is specified.
ExpiresActive on | off	Enables or disables the generation of the Expires header for the documents generated from the directory in which the .htaccess applies. If set to off, no Expires header will be generated unless overridden at a lower level. If set to on, the header will be added (following any applicable ExpiresByType and ExpiresDefault directives.)
ExpiresByType mimetype <code>seconds	Defines the value of the Expires header generated for documents of the specified type (i.e. text/html). The second argument specifies the number of seconds added to the base time to construct the expiration date. A <code> of M indicates that the files last modification time should be used as the base time, an A means the client's access time should be used. i.e. ExpiresActive on # enable expirations ExpiresByType image/gif A2592000 # expire GIFs after one month ExpiresByType text/html M604800 # expire HTML files one week after they were last changed
ExpiresDefault <code>seconds	Sets the default algorithm for calculating the expiration time of all documents generated from the directory in which the .htaccess applies.
PrependMacro mimetype <macro-name>	Prepend a macro data (from config/macros.ini) to the output of all content matching the mimetype served from the directory in which the .htaccess applies.
AppendMacro mimetype <macro-name>	Append a macro data (from config/macros.ini) to the output of all content matching the mimetype served from the directory in which the .htaccess applies.
PrependScript mimetype <script-file>	Prepend a Sambar Server script file to the output of all content matching the mimetype served from the directory in which the .htaccess applies. Important: The path to the script-file is always relative to the documents directory; the script-file must begin with a slash (/). Usage Note: The PrependScript is not evaluated until the initial contents of the request file are returned. Because of this, any script assignments in the request file that utilize variables from the PrependScript must appear after the <HTML> header. the
AppendScript mimetype <script-file>	Append a Sambar Server script file to the output of all content matching the mimetype served from the directory in which the .htaccess applies. Note: The path to the script-file is always relative to the documents directory; the script-file must begin with a slash (/).
Compress mimetype	Compress all content generated by the Sambar Server that matches the mimetype served from the directory in which the .htaccess applies. Note: Content is only compressed if the client sends Accept-encoding: gzip in it's header, reglardless of this directive.
NotifyOnChange e-mail address(s)	Send an email notifycation to the comma-separated list of users specified if a file is created, updated, or deleted to the directory in which the .htaccess applies. The SMTP Server parameter or mail server must be configured to allow the sending of mail. Note: This parameter will typically be applied to modifications made via the FTP server or Document Manager.
RedirectMatch [permanent | temp | gone] <regex-match> <url>	Redirect all requests that match the regular-expression (<regex-match>) to the URL specified. For example: RedirectMatch permanent (.*)\.gif$ /moved.html
options <key-word(s)>	The options directive allows you to control what actions someone may take in this directory and sub-directories. You may specify one or more of the following keywords. none No features are allowed all All features are allowed NoExec Scripts are not allowed to be executed in this directory (applies to Sambar Server *.stm, CGI scripts, ISAPI, and SSI includes that execute either CGIs or non-virtual file paths.) NoIncludes Server-side includes are not allowed in this directory NoCGI CGI scripts are not allowed to be executed in this directory NoDirlist Directory listings are not permitted. RequireSSL Access to the contents requires use of the SSL interface.

Using Groups
By default, the groups restriction applies to the single group associated with the user in the Sambar Server config/passwd file. However, a group file can be created and used to associate a user with numberous groups. A groups file is also convienent if there are many users for a given user authentication area.

A group file consists of lines giving a group name followed by a space-separated list of users in that group. For example:

engineering: tod billy
marketing: stacia admin

Limiting Methods Differently
In the example .htaccess file above, the require directive is not given inside a <LIMIT> section. This is valid in both the Sambar Server and Apache, and means that the directive applies to all request methods. You can use the <LIMIT> section to specify the request methods to which the directive applies:

<LIMIT GET POST PUT DELETE FTP>
require valid-user
<LIMIT>


For example, to limit just the PUT method, the .htacess would be:

AuthName     Restricted Uploads
AuthType     Basic

<LIMIT PUT>
require      valid-user
<LIMIT>

Now, only valid Sambar Server users would be allows to PUT (upload) files to the specified directory. Other users (unauthenticated) can use other methods such as GET and POST to access content in the directory.

As the original example illustrates, FTP access to subdirectories may also be restricted using the LIMIT section. This functionality is designed to prohibit access to a subdirectory which an FTP user would otherwise be granted access. So, even though a user might have an FTP "root directory" of /docs, a subdirectory within the /docs directory tree can be restricted.

Regular Expression Hints

Text: . [chars] [^chars] text1|text2	Any single character. Character class: One of chars Character class: None of chars Alternative: text1 or text2
Qualtifiers: ? * +	0 or 1 of the preceeding text 0 or N of the preceeding text (N > 0) 1 or N of the preceeding text (N > 1)
Grouping: (text)	Grouping of text (either to set the borders of an alternative or for making backreferences where the Nth group can be used on the right-hand side of a RewriteRule with the $N)
Anchors: ^ $	Start of line anchor End of line anchor
Escaping: \char	escape that particular char (for instance to specify the characters ".[]()" etc.)