# Introduction

In sqwebmail versions prior to `3.5.0.20030408`, the `logindomainlist` file had rather limited functionality. An administrator could specify a list of domains, one per line. The user would then see a drop down list to the right of the user id field in the `login.html` page. This drop down list was of limited usefulness because it always defaulted to an empty (non-existant) domain. The user would then have to search through the drop down to find the correct mail domain he wanted to log in under. In addition, the drop down had no access controls, and it showed EACH user ALL of the domains listed in the `logindomainlist` file.

The above functionality is still available, and the new `logindomainlist` functionality is 100% backward compatible. However, the `logindomainlist` file syntax has been extended and is now MUCH more useful. For example, administrators can now specify a group field for each drop down menu record and selectively display only the domains for which each user is a member. In addition, the new file syntax allows administrators to specify default domains so that their users don't have to search for domains in the drop down list.

What if you don't want to display a drop down menu? Administrators can now specify records that generate a hidden field in `login.html`, or an editable text field, allowing sqwebmail to show only one mail login domain to each user per access URL or IP address. This functionality can greatly reduce confusion for first time webmail users, and greatly speed the login process for frequent webmail users.

Finally, the new `logindomainlist` file offers a new tool to ease maintenance. Administrators can now use wildcards to "rewrite" the domain portion of the access URL to the mail domain equivalent. For example, the following record can rewrite the URL "`mail.*.com`" to the mail domain "`*.com`"

`*.com:mail.*.com:@`

This powerful wildcard functionality can ease the login process for most of your server's mail domains with just one or two `logindomainlist` records.

# File Format

Let's take a look at the NEW `logindomainlist` file format:

`firstfield:secondfield:thirdfield`

Above, we can see that the new `logindomainlist` records are made up of three fields delimited by colons. But what does each field do?

`First Field` - the first field contains the "mail domain" for which we would like the user to log in under. The mail domain is the part of an email address after the @ symbol. For example, in the email address "`user@domain.com`", "`domain.com`" is the mail domain.

`Second Field` - the second field contains the "access domain". The access domain contains an URL or IP address that is used to figure out which mail domain to use by default. For example, in the following `logindomainlist` record:

`domain1.com:domain2.com`

"`domain2.com`" is the "access domain" and "`domain1.com`" is the "mail domain". If the user logs into the following URL:

`http://domain2.com/cgi-bin/sqwebmail`

His default "mail domain" will be "`domain1.com`".

`Third Field` - the third field may contain a modifier. The modifier may be either a single character modifier, or a group identification string. The single character modifiers and the group modifier are described in detail below.

Finally, the `logindomainlist` file may also contain comments and empty lines. Empty lines can be used to group records visually, and comments can be used to explain why a certain record or group of records look the way they do.

If the first character of a line is a '#', then the entire line is considered a comment and is ignored. If the first character of a line contains whitespace, the entire line is assumed to be an empty line and is ignored.

# Modifiers

`@` - the '@' modifier can be used to create a hidden field on the `login.html` page which contains the default mail domain. In addition, this field will automatically display the default mail domain in plain text to the right of the userid text box.

NOTE: The '@' modifier ALLOWS the use of wildcards to automate the relationship between "access domains" and "mail domains". See the heading "Wildcards" below for more information about wildcarding.

`-` - the '-' modifier can be used to create an editable text field on the `login.html` page which contains the default mail domain.

NOTE: The '-' modifier ALLOWS the use of wildcards to automate the relationship between "access domains" and "mail domains". See the heading "Wildcards" below for more information about wildcarding.

`group string` - If no modifier is specified in the third field, or if the third field modifier is a group identifier string, then a drop down menu will be displayed on the `login.html` page. Records with the SAME group string will be displayed together in the drop down. For example, if your `logindomainlist` file contains the following records:

         domain1.com:domain2.com:firstgroup
         domain3.com:domain4.com:firstgroup
         domain5.com:domain6.com:firstgroup
         domain7.com:domain8.com:secondgroup
         domain9.com:domain10.com:secondgroup

And the user logs into sqwebmail with the following URL:

`http://domain4.com/cgi-bin/sqwebmail`

He will see a drop down containing ONLY the following domains:

         domain1.com
         domain3.com
         domain5.com

"`domain3.com`" will be automatically selected, or defaulted. Only the records in the `firstgroup` will be visible to the user. This functionality is great for organizations with more than one mail domain.

NOTE: The group string modifier does NOT allow the use of wildcards to automate the relationship between "access domains" and "mail domains". This is because drop down menus are fundamentally incompatible with wildcards.

# Wildcards

If a record's modifier allows wildcarding (See "Modifiers" above for information about which modifiers allow wildcarding and which do not.) then the first and second fields of that record _MAY_ contain wildcards. Wildcards match against the HTTP_HOST CGI environment variable only. IP addresses can NOT be used if either the first or second fields contain the wildcard character. However, if neither the first nor second fields contain the wildcard character, then the second field can contain an IP address.

In the `logindomainlist` file, an asterisk (*) character in either the first and/or second field represents a wildcard. Any asterisk in the second field will be used to match an access domain. If an asterisk exists in the first field then any characters which the asterisk in the second field represents will replace the asterisk in the first field when sqwebmail determines the default mail domain. However, asterisks are not required in either the first or second fields. They are totally optional. For example, given the following `logindomainlist` record:

`*.com:mail.*.com:@`

If the user logs into sqwebmail with the following URL:

`http://mail.mydomain.com/cgi-bin/sqwebmail`

The asterisk in the second field will represent the string "`mydomain`". This string will then replace the asterisk in the first field to give the following default mail domain: `mydomain.com`

Similarly, if the following record exists in the `logindomainlist` file:

`*:*:@`

Then ANY URL the user uses to access sqwebmail will be automatically used for the default mail domain.

But the first field doesn't _HAVE_ to contain an asterisk. The following will work just fine:

`mydomain.com:mydomain.*:@`

The above example will allow the user to access the "`mydomain.com`" mail domain from any of the following URLs: "`mydomain.org`", "`mydomain.net`", "`mydomain.us`", etc...

And finally, the first field doesn't have to contain anything at all! If the first field is empty, that record will serve as an explicit no-default mail domain. No default mail domain will be specified if the second field matches the user's login URL. This is useful because the `logindomainlist` is searched from the top down. Any wildcard records at the bottom of the list will be overridden by records closer to the top. An "explicit no-default" record can be used to specify certain domains as "system account" domains so that no default mail domain is specified.