The Server Administrator can use any Web browser application to
configure and to monitor the Server remotely, using the Web (HTML) forms.
The authentication schemes supported with the HTTP protocol protect the WebAdmin pages from
an unauthorized access. In order to access the WebAdmin pages, the user should provide the name
and the password of a CommuniGate Pro Account with required Server Access Rights.
By default, the HTTP Admin module accepts clear text TCP/IP WebAdmin connections on
the port 8010 and secure (SSL/TLS) connections on the TCP port 9010.
To access the WebAdmin pages, the Server administrator should use the
following URLs:
http://domain.com:8010
https://domain.com:9010
where domain.com is the CommuniGate Pro Main Domain name or its alias,
or the IP address of the CommuniGate Pro Server.
Server configuration errors can cut you off the WebAdmin Server Interface, if all your Server
IP addresses and DNS names are assigned to secondary Domains.
To access the WebAdmin Server Interface, use the following URLs:
- http://sub.domain.com:8010/MainAdmin/
https://sub.domain.com:9010/MainAdmin/
where sub.domain.com is any name pointing to your Server computer or any
of the Server IP addresses.
If the CommuniGate Pro Server supports several Secondary Domains,
the same port can be used by the Domain Administrators to access the Secondary Domains settings and account lists.
A Domain Administrator should access the server using the following URL:
- http://sub.domain.com:8010
https://sub.domain.com:9010
where sub.domain.com is the name of the secondary Domain to administer.
The Server will ask for a user (Account) name and a password, and if the specified
Account has the Domain Administrator access right, the list of the Domain Accounts is displayed.
Sometimes this URL cannot be used. For example, a secondary Domain may
have no DNS A-records (only MX records). To access such a Domain,
its Domain Administrator should use the following URL:
- http://domain.com:8010/Admin/sub.domain.com/
where:
- domain.com is the name of the Main Server Domain or its alias,
or the IP address of the CommuniGate Pro Server.
- sub.domain.com is the name of the Domain to access.
Other Domains can specify your Domain as their Administrator Domain.
The Domain Settings page of your Domains provides a list of those Domains:
You can open their WebAdmin Domain Interfaces using the links on this page.
Remember that you should login using your full Account name (yourAccountName@yourDomainName)
when accessing other Domain WebAdmin pages.
CommuniGate Pro users can connect to the CommuniGate Pro Server with any Web browser
(via the HTTP protocol) to manage their Accounts, to browse their Mailboxes, to read, copy,
delete, forward, and redirect messages, to move messages between Mailboxes, to compose and
submit new messages, etc.
This CommuniGate Pro component is called the WebUser Interface.
Registered users and guests can also use this component to browse Mailing List archives.
By default, the HTTP User module accepts clear text TCP/IP connections on the
TCP port 8100, and the secure connections - on the TCP port 9100. If your Server does not have
to coexist with some other Web Server on the same computer, it is recommended to change these
port numbers to 80 and 443 - the standard HTTP and HTTPS port numbers.
In this case your users will not have to specify the port number in their browsers.
CommuniGatePro users can user their Account File Storage as personal Web sites.
See the File Storage section for the details.
The URL for the accountName@domainName File Storage (or personal Web site) is:
- http://domainName:port/~accountName
- https://domainName:port/~accountName
where port is the HTTP User ports (8100 and 9100 by default).
The list of files in that File Storage can be seen at:
- http://domainName:port/~accountName/index.wssp
- https://domainName:port/~accountName/index.wssp
This page can be used to manage the File Storage.
It is available to the Account owner, Domain Administrators or, and to authenticated user granted the File Access Rights .
The "davmount" (RFC4709) document can be retrieved using the following URLs:
- http://domainName:port/~accountName/davmount
- https://domainName:port/~accountName/?davmount=1
You can specify an alternative File Storage prefix using the Domain Settings.
That setting can be an empty string, in this case personal Web sites can be accessed using the following URLs:
- http://domainName:port/accountName/
- https://domainName:port/accountName/
You can also use the CommuniGate Pro Router to access personal Web sites with
domain-level URLs. See the Routing section below.
Use the WebAdmin Interface to configure the HTTP modules. Open the Services pages in the Settings realm,
then open the HTTPA (Admin) and/or HTTPU (User) page.
- Log Level
- Use this setting to specify what kind of information the HTTP
module should put in the Server Log. Usually you should use the Major
or Problems (non-fatal errors) levels. But when you experience
problems with the HTTP module, you may want to set the Log Level setting
to Low-Level or All Info: in this case protocol-level
or link-level details will be recorded in the System Log as well.
The HTTP Admin module records in the System Log are marked with the HTTPA tag.
The HTTP User module records in the System Log are marked with the HTTPU tag.
- Channels
- This setting is used to limit the number of
simultaneous TCP/IP connections the HTTP module can accept. Most browsers
open several connections to load an HTML page and all embedded pictures,
so do not set this limit to less than 5, otherwise some browsers may fail
to download embedded graphic objects.
- listener
- Follow this link to open the HTTP Admin Port or HTTP User Port
listener settings. There you can specify the
TCP port number(s) the service should use, the interfaces to use, and other options.
If the CommuniGate Pro Server computer runs some other Web Server application,
you should specify a port number in the "secondary range" to
avoid conflicts with that other Web Server application. Usually the "secondary"
Web Servers use ports numbers in the 8000-8100 range. If you set the port
number to 8010, you will be able to connect to your server by entering
http://xxx.yyy.zzz:8010 in your Web browser, where xxx.yyy.zzz
is the exact domain name (A-record) or the IP address of your Server.
- Request Size Limit
- This setting limits the maximum size of an HTTP request the Server accepts. You may want to increase this
limit if you want to allow your users to upload larger files and/or to attach larger files to messages composed using he
WebUser Interface.
- Support Keep-Alive
- If this option is enabled, the CommuniGate Pro supports the Keep-Alive protocol feature, so a user browser
can retrieve several files using the same HTTP connection. Some browsers do not implement this function correctly
and they may have problems if this option is enabled.
- Compress If Larger
- If the composed response size is larger than the value of this option, and the client browser supports compression,
the response is compressed before being sent to the client.
- Scan Large Requests
- If this option is disabled, and the size of a HTTP request to be received exceeds the specified limit,
the Server sends an error response and closes the connection. Many browsers do not display the error response
in this case. Instead, they display a generic "connection is broken" message.
If this option is enabled, the Server sends an error response back and receives the entire request (but it does not store
it anywhere). The user browser then displays the error message.
- Advertise Basic AUTH, Advertise Digest AUTH,
Advertise NTLM AUTH, Advertise Negotiate AUTH
- If these options are enabled, the Server will inform browsers that clear-text (Basic) or secure (Digest, NTLM, Negotiate/SNEGO) authentication methods
are available. If you plan to connect to the WebAdmin Interface via clear-text (non-encrypted) links over the Internet,
you may want to enable these options. Different browsers work differently when these options are enabled. Some may fail,
some may still use the clear-text (Basic) authentication method, so enable these options only if needed.
Note: the GSSAPI (Kerberos) authentication methods become available when the Negotiate AUTH method is enabled.
The HTTP modules set the MIME Content-Type for every object they send. To detect
the proper Content-Type for plain files, the modules use the file name extension and the following
"basic" built-in table:
File Extension | MIME type |
html | text/html |
txt | text/plain |
gif | image/gif |
jpg | image/jpeg |
css | text/css |
js | text/javascript |
There is also an "extended" built-in table, which is displayed on the WebAdmin page.
You can create your own custom extension table by specifying additional file name extensions and corresponding
MIME Content-Types:
The extended "built-in" table is displayed under the custom table.
When a file extension is converted into a MIME type, the custom table is checked first, then the built-in tables are checked.
As a result, you can redefine the built-in table values with the custom table values .
The HTTP modules use the Router to process all address it receives.
But unlike other Access modules, the HTTP modules often deal not with complete E-mail addresses, but with domain names only.
When the HTTP Admin module receives a request, it uses the name
or the IP address specified in the URL to decide which Domain Administration pages to display.
When the HTTP User module receives a request, it uses the name or the IP address
specified in the URL to decide which Domain (its login page, Mailing Lists, File Storage, etc.) to access.
In order to support all types of CommuniGate Pro Routing features (Router Table, Domain Aliases, IP
Address to Domain Mapping, etc.), the HTTP module composes a complete E-mail address LoginPage@domainname
(where domainname is the domain name specified in the request URL), and then it processes this
address with the Router:
- If the LoginPage@domainname address is routed to any module other than LOCAL, an error is returned.
- If the LoginPage@domainname address is routed to the LOCAL module and local part of the resulting address
is still LoginPage, then the domain part of the resulting address is used
to open the proper CommuniGate Pro Domain.
- If the address is routed to the LOCAL module, but the resulting username is not LoginPage,
the File Storage of the addressed Account is opened. If the resulting
address has a local part, then the File Storage subdirectory with that name is opened.
Samples (Router Table records, domainA.com is a CommuniGate Pro Domain):
- mail2.domain.com = domainA.com
- When the http://mail2.domain.com/ URL is used, the <LoginPage@mail2.domain.com>
address is routed to <LoginPage@domainA.com> address, and the domainA.com Web Interface is opened.
- <LoginPage@mail2.domain.com> = user@domainA.com
- When the http://mail2.domain.com/ URL is used, the <LoginPage@mail2.domain.com>
address is routed to LOCAL account user@domainA.com, and the user@domainA.com File Storage is opened.
- <LoginPage@mail2.domain.com> = subDir@user@domainA.com.domain
- When the http://mail2.domain.com/ URL is used, the <LoginPage@mail2.domain.com>
address is routed to the LOCAL account user@domainA.com with the subDir local address part,
and the subDir directory of the user@domainA.com File Storage is opened.
The HTTP User module can start CG/PL Web Applications.
Use the WebAdmin Interface to open the HTTP User settings page:
- URI Path Component
- The URI (Universal Resource Location) component, after the first slash (/) symbol.
The component may contain the asterisk (*) symbols.
- Web Application
- The name of a CG/PL Web Application to start. Each domain may have its own version of the application.
Web Applications can be used to extend functionality of the WebUser Interface.
Web Applications are used to implement the Microsoft "Autodiscover" and Mozilla Thunderbird Autoconfiguration protocols.
The HTTP User module can start CGI programs and scripts. To access a CGI program,
the /cgi-bin/programName URL should be used, and the programName program
should be placed into the CommuniGate Pro CGI Directory.
Use the WebAdmin Interface to open the HTTP User settings page:
- CGI Directory
- Enter the name of the server system file directory where your CGI programs are located.
If that directory is inside the CommuniGate Pro base directory, then you can specify its
relative name, otherwise specify the full path to that directory. The CGI Directory should not have
any subdirectories.
- File Extensions
- While some operating systems (such as Unix) can start various interpreter-type programs/scripts
by starting the proper interpreter, other operating systems require that the interpreter program is started
explicitly. The CommuniGate Pro Server supports those operating systems by allowing you to specify
the name of the interpreter program for certain file extensions. As a result, when the CommuniGate Pro
Server needs to start a program or script with the specified extension, it forms the OS-level
command line by prefixing the program/script name with the specified interpreter program name.
In the above example the Server will process the /cgi-bin/script.pl URL by
executing the
- Perl.exe script.pl
command.
Note: the interpreter program name must be registered in the Child Processes Manifesto.
- HTTP Header Field
- Use this table to specify custom, non-standard HTTP Request header fields that you want to pass
to your CGI applications. If a request contains a header line with the specified field name, the line is
passed to CGI applications as an environment variable with the HTTP_H_convertedFieldName name,
where convertedFieldName is the field name in the uppercase letters, with all minus (-) symbols
substituted with the underscore (_) symbols.
CGI programs can be used to extend functionality of the WebUser Interface.
They can log into the Server via its PWD module to do some CLI/API operations and/or
via the IMAP or XIMSS modules to access and modify Mailbox data.
To simplify these login operations, CGI programs can use the SessionID Authentication method.
The HTTP User module provides access to the Server Command Line Interface/API via the /CLI/ realm.
Text Method
Send a GET or POST request with a command parameter. The parameter value should contain the CLI command to be executed.
If the request fails, the error code is returned as an HTTP response error string.
If the request is successful, the HTTP response code is 200.
If the request produced an output, the text representation of the resulting object is sent as the HTTP response body.
SOAP Method
Send a SOAP XML request. The request should have exactly one XML element - the CLI command to execute.
The XML element tag is the CLI command tag.
the XML element sub-elements are XML representations of parameter objects
and/or key elements. The key element text body is a CLI command key.
- Example:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<createAccount>
<param>newuser@domain.dom</param>
<param>TextMailbox</param>
<param>
<subKey key="RealName">John Doe</subKey>
<subKey key="Password">soappass</subKey>
</param>
</createAccount>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This request is converted into:
createAccount "newuser@domain.dom" TextMailbox {RealName="John Doe"; Password="soappass";}
If the request produces an output, its XML representation is added to the SOAP response.
- Example:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<getAccount>
<param>newuser@domain.dom</param>
</getAccount>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This request is converted:
getAccount "newuser@domain.dom"
and a dictionary output is produced:
{Password="\001xxxxx"; RealName="John Doe";}
This response is sent with the SOAP response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<response>
<object>
<subKey key="Password">\001fjh{\024hdfu</subKey>
<subKey key="RealName">SOAP Test</subKey>
</object>
</response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The HTTP Client functionality is used to send HTTP Requests to remote servers. It is used with:
- CG/PL HTTPCall function.
- XIMSS retrieveURL operation.
Use the WebAdmin Interface to specify the HTTP Client processing parameters.
Open the General pages in the Settings realm, and find the HTTP Client Manager panel on the Others page:
- Log
- Use this setting to specify what kind of information the HTTP Client Manager should put in the Server Log.
The HTTP Client Manager records in the System Log are marked with the HTTPO tag.
- Cache
- Use this setting to specify how many HTTP connections the Manager should keep open, increasing the processing
speed for requests sent to the same remove HTTP server (these requests will reuse already open connections).
The HTTP module sends a request to the specified http: or https: URL.
The module accepts an optional parameter dictionary which can contain the following elements:
- method
- If this element is specified, it specifies the HTTP request method (GET, MOVE, etc.)
If this element is not specified, the HTTP request method is set to GET if the body element is absent, otherwise the POST method is used.
- urlParams
- This optional element value should be a dictionary. All its key-value pairs are sent as URL parameters in the HTTP request line.
Each dictionary value should be either a single value - a string or a number, or an array of single values.
For an array-type value, a URL parameter for each array element is composed separately, using the same dictionary key.
- Content-Type, Content-Subtype
- These optional elements specify the Content-Type header field for the HTTP request.
- body
- If this optional element value is a dictionary:
- the HTTP body is composed as "form data"
- if the method element is specified, it must be POST
- if the Content-Type element is not specified, the request Content-Type field is set to multipart/form-data.
- if the Content-Type element is specified, it must be multipart, otherwise the Content-Subtype must be specified, too, and it must be set to x-www-form-urlencoded.
- if the Content-Type element is not specified or if it is set to multipart, request body form data is composed using the mutlipart/form-data format,
otherwise the x-www-form-urlencoded format is used.
- each dictionary value should be be either:
- a single value - a string, a number, a datablock, a dictionary
- an array of single values
For an array-type value, form data for each array element is composed separately, using the same dictionary key.
If a single value is a dictionary, its empty-string ("") element value is used. If the request uses the mutlipart/form-data format, then
the dictionary Content-Type, Content-Subtype, and (optionally) charset string element values are used to compose the
form element Content-Type header field, and the filename string element (if it exists) is added to the form element Content-Disposition header field.
Example:
The following body element:
{
field1 = "value1"; field2 = #145;
field3 = [YWJjYWJj]; field4 = ("value2",#777);
field5 = {"Content-Type"="image"; "Content-Subtype"="png"; "" = [shjhsjhkwuyuieyriuyuiyi];};
}
will be sent as
--_______________post-field_
Content-Disposition: form-data; name="field1"
value1
--_______________post-field_
Content-Disposition: form-data; name="field2"
145
--_______________post-field_
Content-Disposition: form-data; name="field3"
abcabc
--_______________post-field_
Content-Disposition: form-data; name="field4"
value2
--_______________post-field_
Content-Disposition: form-data; name="field4"
777
--_______________post-field_
Content-Disposition: form-data; name="field5"
Content-Type: image/png
binary data
--_______________post-field_--
If this optional element value is a string:
- the string is copied line-by-line into the request body
- the string EOL (End Of Line) separators are replaced with the Internet EOL (<carriage-return><line-feed>) symbols
- if the Content-Type element is not specified, the Content-Type field is set to text/plain.
If this optional element value is a datablock:
- the datablock is used as the request body
- if the Content-Type element is not specified, the Content-Type field is set to application/octet-stream.
If this optional element value is an XML Object:
- the XML Object text presentation is copied into the text body.
- if the Content-Type element is not specified, the Content-Type field is set to text/xml.
- charset
- If this optional element is specified, it should be a name of a known character set.
The request body is encoded from the UTF-8 encoding into the specified character set,
and the charset=charset_name parameter is added to the Content-Type header field.
If this element value is an empty string, no charset=charset_name header field parameter is added.
If this element is not specified, the charset=utf-8 header field parameter is added, but only if the Content Type of the request body is text.
- closeConnection
- If this element is specified, the module adds the Connection: close header field to the request.
- User-Agent
- If this element is specified, the module uses its string value as the custom User-Agent header field value.
If this element value is an empty string, this header field is not sent at all.
- Cookie
- This optional element value should be a string. It is used as the Cookie header field data.
- If-Modified-Since
- The optional element should be either a timestamp or a string in the iCalendar date-time format.
This element sets the HTTP request If-Modified-Since header field value.
- responseFormat
- This optional element specifies how the HTTP response body should be converted (see below).
- authName, authPassword
- These optional elements specify the credentials to send with the HTTP request.
- timeout
- If this optional element is specified, it should be a number or a numeric string. Its value specifies the time-out for the HTTP request(s) sent.
This value cannot exceed the maximum time-out value specified with the calling Server component.
If this element is not specified, the maximum time-out value is used.
- redirectLimit
- This optional element specifies how many time the HTTP module can resend the request to the new destination (URL)
when it receives a 3xx response from a remote server
If this element is not specified then the module resends a GET or HEAD up to 3 times,
and does not resend other requests.
- Via
- This optional element specifies the hostname or IP address to which the connection should be made to send the request. The Host Header and the target domain name in TLS hanshake still use the name specified in the URL or with the Host key.
- supplFields
- This optional element is a dictionary. The dictionary keys specified additional HTTP request field names,
and the dictionary values (which should be strings or arrays of strings) specify the HTTP request field values.
- supRespFields
- This optional element is an array. The array elements specify supplementary HTTP response fields.
If this element is specified and the request response contains the corresponding fields, the resulting dictionary contains the element supRespFields.
The module returns either an error code, or a result dictionary with the following elements:
- responseCode
- The numeric value of the HTTP response code (200 for successful operations, 300-399 for "redirect" responses the module has not processed itself, 400-599 for failed operations).
- responseText
- A string containing the information text part of the HTTP response line.
- Content-Type, Content-Subtype
- Strings containing the response body content type and subtype.
- charset
- A string with the response body charset. If this element is present (it was specified as the charset=charset_name parameter of the HTTP response Content-Type header field,
the response body is encoded from that character set into the UTF-8 encoding.
- body
- This element exists if the HTTP response contains a non-empty body. This body is converted into the
body response element according to the responseFormat request element value.
If the responseFormat request element is not specified, the response Content type and subtype are used:
responseFormat | Content-Type (if responseFormat is not specified) | converted to |
xml | */xml, */*+xml |
the body is interpreted as a text presentation of an XML Object. The body element is the XML Object read |
calendar | */calendar |
the body is interpreted as an iCalendar text. The body element is an iCalendar XML Object presenting the parsed body text. |
empty string | */* |
The body element is a datablock containing the HTTP response body. |
If the module fails to convert the HTTP response body, then it returns an error if the responseFormat was specified.
If the responseFormat was not specified, then the HTTP response body is returned as a datablock.
- Date, Last-Modified, Expires
- Timestamp elements with the HTTP response header field values.
- Server, Location
- String elements with the response header field values.
- Set-Cookie
- String or array of strings with the response header field value(s).
- supRespFields
- A dictionary containing supplementary response header fields and their values. This element is returned if supRespFields was specified in the request and the HTTP response contains the corresponding header fields.
|