|
Server Configuration
Server Configuration The SQLData Server uses a configuration file for environment settings, runtime parameters, message handler definitions and access controls. It is a text file that should be stored under the Config subdirectory. There can be multiple instances of the server running on a machine. Each instance can have its own configuration file. The configuration file can be passed as one of the command line parameters, for example, SQLData -config MyConfigFile.ini Instructs the server to use MyConfig as its configuration file. The default configuration file is sqldata.ini. The configuration file is an important port of the web server because it controls the behavior of the server. Each setting in the configuration file has a name and a value. The type of the value can be either numeric or string based on its meaning. The name and value are separated by an equal sign, for instance: License = trial.lic Spaces between name and value are insignificant. The server also takes out the leading and trailing spaces. Each setting should occupy a single line. A line start with semicolon is treated as a comment line. This document describes the meanings of the settings in the configuration file.
Numerical. The value designates whether the servers perform user authentication or not. The server sends an HTTP challenge to the client browser if the setting is 1. The client browser will display a login dialog box after receiving the challenge. The server validates user's name and password before granting access when authentication is enabled. On the server side, user name and password are stored in the file sqldata.usr. The password and the file are digitally encrypted. The user logon is disabled if Authentication is set to 0.
Although the authentication can prevent unknown user from gaining access to the server, the mechanism is not quite secure because user name and password are sent as clear text. The setting should be set to 1 if session control is desired (A user session is established when he/she logs on to the server). Numerical. The server maintains session information (such as database connection, database record set, user id, etc) for each users. This could potentially increase server performance when transaction is heavy. SessionType is used for controlling how the sessions are to be managed.
The Authentication parameter should normally set to 1 if session is to be cached as a session is established only when a user is logged on. Shared session is useful in a situation that no authentication is needed. All sessions are treated as shared resources. Unique session should be used if security is a concern. The server automatically removes a session if there is no activity for a period of time. The session expiration time is determined by the SessionIdleTime setting. The server may elect to keep a session for a longer period of time if the number of connections is small.
String. This value specifies valid IP addresses that are allowed to connect to the server. Machines with IP address out of the specified range will be denied for services. Each IP address can be a regular expression with '*' and '?' as the wild characters. For instance, 205.215.34.* stands for IP address in 205.215.34.0 to 205.215.34.255 205.21?.34.234 represents IP address from 205.210.34.234 to 205.215.34.234 Multiple IP address should be separated by the ';' character. For example, ValidIP=203.212.34.*;203.212.35.* Specifies two sub network addresses as valid IP addresses. The following setting grant access to machine of all IP addresses: ValidIP = *
It is a good idea to use ValidIP for granting access to friendly machines. These may be machines in your company or in an Intranet.
String. This value specifies IP addresses that will be denied for services. The server will not respond to requests from these hosts. Each IP address is a regular expression (See ValidIP for reference), and multiple IP strings are separated by the colon sign.
This is setting is useful for denying services to hostile machines.
Numerical. The server runs in multithread mode if the parameter is set to 1. Each request will be served by at least one thread. There could boot server performance under heavy transaction. The server runs in single thread mode in serving requests if the parameter is set to 0 although the server may still use multiple threads for other purposes. A request is not served until all the previous requests have been fulfilled in this mode.
There are ODBC drivers that are not thread-safe. These ODBC drivers do not function properly in multithread application. The parameter should be set to 0 for normal database operation. You may also want to turn multithread off in debug mode.
Numerical. The value specifies maximum number of sessions the server should cache. The server creates a session in response to a service request. To improve efficiency, the server keeps some number of sessions in memory so that message can be dispatched immediately. It is good idea to set the maximum number of handler to 200 and increase it as traffic increases.
Caching sessions normally increases the server performance if there is sufficient memory in your machine. The server begins to remove older sessions from its cache if the number of sessions reaches to the maximum.
Numerical. This is the maximum number of rows in a query result that the server returns to the client. This applies when a SQL query is issued and there are too many records selected. Clients can always request next set of result when needed. The maximum number limits the number of records can be displayed in user's browser. The parameter is used as default. The MaxRows parameter in the HTTP request overwrites the setting. For example, the following request, http://www.yourhost.com/QueryPage.html?MaxRows=500forces the server to use 500 as the maximum rows to be returned.
String. The value specifies the default ODBC data sources (DSN). The server uses this DSN to connect to the database when needed. The parameter could be just the ODBC DSN if no login is needed. It should be an ODBC connection string if user name and password is required. The format of the connection string is: DSN=mySQL;UID=UserName;PWD=YourPassword
This setting is very useful if you have only one kind of database. In all your HTML files and user requests, no database needs to be specified, the server uses the provided DataSource setting to access the database.
Numerical. The server Caches database connection if the parameter is set to 1. The cached database connection will be reused by different users.
Connecting to a database is one of most expensive operations in ODBC. The overhead can be dramatically reduced if the database connection is cached. There are situations, however, in which each user must have an independent connection. The setting should be turned off if you experienced sharing related problems.
String. This is the name of the file where the server puts debugging information. It should not contain any path information as the file is always in the LOGS subdirectory. The file is only used when the server is running in the debug mode. The server outputs detailed information into the file during processing client requests. The server automatically generates a file name in the following format if the parameter is not specified: DEBmmddyy.LOG Where mm is month, dd is day and yy is year.
The parameter is normally unnecessary as the server creates new files automatically.
String. This is the name of the file where the server puts debugging information. It should not contain any path information as the file is always in the LOGS subdirectory. The file is used for logging user requests and server activities in a standard HTTP logging format. The server also outputs error messages into the file. The server automatically generates a file name in the following format if the parameter is not specified: LOGmmddyy.LOG Where mm is month, dd is day and yy is year.
The parameter is normally unnecessary as the server creates new files automatically.
String. These are two special strings that enclosing commands for the server to processing in the HTML files. The server executes commands in between the markers and sends the output of the command to the client. The default settings are: MarkerStart = [ MarkerEnd = ] Any strings in between the square brackets are special commands, Refer to the Template Token Commands and Server Scripting Guide for more details. Users normally can not see the strings in between the markers in your HTML files as they are consumed by the server. Some web developers prefer to use the HTML comments as the server commands, set the two parameters to: MarkerStart = <!-- MarkerEnd = --> Instructs the server to process all comments in the HTML file. String. This is the name of your license file. It should be in the CONFIG directory. The license file is a digitally encrypted file contains some scope of your license. The server would not work without a valid license file.
Your license file is TRIAL.LIC if you download a trial version of the server. The trial license expires after about 30 days. You will receive a license file from us if you buy the product. Please copy the license file to the CONFIG directory, and set the value of the parameter as the name of your license file.
String. The SSL version number. It can be either:
The parameter is needed only if SSL is enabled. We recommend that 23 be used.
This parameter is ignored unless the ServerCertificate is also specified.
String. This is the name of your certificate file signed by a Certificate Authority (CA). The parameter must be set for SSL operations.
Your certificate should be put in the CERTS subdirectory.
String. This is the encryption algorithm used by the SSL protocol. The value should be set to SSLv3 so that the server will negotiate a common encryption method with the client.
There are other encryptions that can be used for the SSL operations. Please contact tech support if a special cipher must be used in your environment.
String. This is the name of the file that contains the public keys of accepted certificate authorities. Certificate signed by other CA will be rejected.
You should not modify the setting in normal situation. The server shipped with a list of well-known CA certificates. The file is under the CERTS directory. String. This is an arbitrary string that is used to for securing communication between servers. The SQLData Enterprise Server supports Dynamic Server Groups (DSG), in which group of servers collaborate with each other to serve user requests. The server uses the string to encrypt data before sending to another server if the parameter is specified. Only servers with the same secret can communicate properly. The secret string must start with the '@' character.
It is a good idea to use a long random string as the server secret and to make sure all servers in the DSG have the same secret. Secret can also be changed regular for added security. This parameter is valid only for the SQLData Enterprise Server.
String. This is the name and port number of your proxy host in case the server is running behind a firewall. Here is an example of proxy setting: Proxy = bigboy.sqldata.com:80 The port number is normally 80 for HTTP protocol, but consult with your network administrator for the proxy host name and port number in your environment.
The server sends data to the proxy server instead of client machine if proxy is specified. The proxy server is responsible for dispatching the data to the clients. The parameter should be commented out or deleted if no proxy is needed.
String. This is the name and port number of an authentication server. The parameter is for centralized authentication in a multiple server environment. Upon receiving a login message, the server dispatches it to the specified server for verification.
There are several benefits using an authentication server:
The Authentication parameter should be set to 1 for the parameter to have any effect. The ServerSecret should also be assigned so that data from/to the authentication server can be encrypted. The parameter is only used by the SQLData Enterprise Server.
String. Message Filters are plug-in components that either preprocess or post-processing a message. The server loads the message filters at runtime and executes them. The are two kind of handlers:
The value of the parameter is the name of a dynamic linked library with an exported function: Execute. Refer to the developers guide for further information. The values for the filters should be set to empty if unnecessary.
The server passes a Request object and Response object to the filter function so that they can be modified inside these functions. The Request object should only be changed in the input filter. Changing the Request object in output filter has no effect because the message has been processed already.
String. Message handlers are custom-built functions that process messages not handled by the SQLData server. This is where you can plug-in your own components and extend the functionality of the server. A message handler in the configuration file is a name-value pair: MessageName = HandlerFile Where MessageName is a virtual name similar to a virtual directory, and HandlerFile is the name of the Dynamic Linked Library (DLL) that contains handler functions. For example, the server shipped with a database manager, which is defined as a Message Handler: $DBManager = dbextern.dll All HTTP requests in a form of http://www.yourhost.com/DBManagerare handled by the message handlers in the dbextern.dll file. Note that the name of the message handler is prefixed with a '$' to avoid name collisions. Refer to the developer's guide for the technical specification of the message handler and how to create your own. Unlike the message filter, where the server provides the actual operation, the server does not processing a message if a message handler is defined. It is the sole responsibility of the message handler to send response to the client.
String. This is a group of parameters that specify how the server could send an email notification in exceptional situations. There are three parameters:
The server catches internal errors and exception in different levels so that they could not stop the server. However, prompt human intervention is necessary in certain mission critical applications. Email notification is a good way for alarming operators or system administrators when the server encounters unhandled exceptions.
Numerical. In a dynamic server group (DSG), each server is a member of server cluster and plays different roles. This parameter defines how the server should join the DSG. The parameter could be assigned one of the following values:
The server uses IP multicast technique to form a dynamic server group. Any member can join the group and leave the group at any time without affect overall operation (although resources on a down host may be unavailable). The server joins a DSG when it is started and leaves a DSG when it is shutting down. A server should be set as a receiver if databases on the machine are not to be exported. A server should be designated as a broadcaster if it is a second tier server and has no direct client contact.
String. This parameter specifies the Dynamic Server Group address. DSG members use the address to form a cluster and multicast messages through User Datagram Protocol (UDP). The UDPAddress is an IP class D address in the range of 224.0.1.0--239.255.255.255. Some of the addresses in the range are already reserved for wide range multicasting. If there are proxies (WinSock or SOCKS) in your network environment, make sure the datagram is not filtered out. Consult with your network administrator for enabling pocket from/to the specified IP address through your network.
Numerical. This is the port number for UDP socket. There is no special requirement about the port number as long as it is not a well-known port and there is no port conflict in your network. Numerical. This is a time interval in milliseconds. The server uses this timer for multicasting DSG messages. The value determines the multicasting frequency for DSG operation. Each server in a DSG can have different UDPTimer value. The value is used as the base unit for all DSG activities.
Numerical. This defines the type of remote services. The SQLData server offers two type of services, Universal Data Access (UDA) and Remote Procedure Call (RPC), which allow one server to access database on another server transparently. There are three values for the setting:
When a remote service is enabled, the server will broadcast its own databases to the DSG using the specified protocol so that other can access them. On the other hand, the server will also use the protocol to access databases offered by other servers.
String. This specifies the communication protocol used by the remote procedure call layer. The default is TCP/IP. RCPProtocol = ncacn_ip_tcp Other possible protocols such as NetBIOS over IPX or SPX can also be used. Consult Microsoft RPC guide for a complete list of RPC protocols.
ncacn_ip_tcp must be used if servers in the DSG are connected through the Internet. String. Partners of the server are hosts that contain the same databases and perform synchronized operations as this one. The parameter is a string that specifies protocol, host name and port number. For example, Partners = rpc://backup1.sqldata.com:80;uda://backup2.sqldata.com:8732 defines two partners for the server. One server, backup1.sqldata.com, uses remote procedure call (RPC) protocol and the other, backup2.sqldata.com, uses the universal database access protocol (UDA). The SQLData Enterprise server supports UDA protocol by default. RPC protocol can be enabled by setting RPCService to 1. When database operations such as INSERT, DELETE and UPDATE are executed on the host. The server performs the exactly the same operations on its partners to keep their information up-to-date. This is called incremental synchronization.
Partners are very important part of mission critical systems. Partners provide necessary backup when the primary server is down. RPC protocol should be used whenever possible. It has much better performance than the UDA protocol. There is a performance penalty when partners are used because of additional operations on the partners.
String. This is the directory where the server is installed. The server is able to determine the root directory when started. The parameter is needed only when your web pages are not in the default HTDOCS subdirectory.
String. This parameter specifies the default directory for the HTML documents. It is relative to the Root directory as defined above. In other words, the DocRoot must be a subdirectory of the Root.
DocRoot is the default directory where the server looks for HTML documents.
String. A virtual Directory is a directory name that user can use in the URL to access web documents. Virtual directory is mapped to a physical directory using the settings in the configuration file. The name of a virtual directory must start with character '/'. For example, /images = resources\images defines a virtual directory /images, which is mapped to a subdirectory resource\images under the server root directory. Suppose the root directory is \sqldata2.0, then the absolute physical directory would be \sqldata2.0\resource\images. Any number of virtual directories can be defined in this way as long as virtual directory names do not collide with other settings in the configuration file. Physical directories should be under the root directory for security reasons. There are cases where multiple web sites coexist on the same host (virtual domain), a separate configuration file should be used for each instance of the SQLData server in such environment.
String. This is a list of directory names separated by semicolon. The server uses the setting to search template files or included files. As the matter of fact, the server searches all directories in the list for a file that could not be located in the default directory (usually the document root). The directories in the list should be relative directories to the root directory.
Another use of TemplateDir is to organize files in different physical directories, they can be, however, accessed from the document root.
String. DefaultPage is the home page of a web. The page is displayed when a user types in http://www.yourcompany.com
Index.html will be used as the default home page if the parameter is not specified.
String. This is a group of settings that specify what should be sent to client when an HTTP error has occurred. These errors range from bad request, forbidden access to internal server errors. Each HTTP error can have an error page associated with it. The format of the error page is Errornnn = MyErrorPage.html where nnn is the HTTP error code. Refer to HTTP 1.1 specification for a complete list of error code. A default error page is sent to users if corresponding error page is not defined. The error page definition covers only HTTP errors. Database errors are handled through a parameter in HTTP requests.
String. A user group is defined as a single character proceeded by a '@' sign. The value of the group is a string represents access rights granted to the group. For example, @s = rwem defines a user group s with access rights 'rwem'. Each character in the string stands for a particular right and its meaning is determined by the Operation setting Rights (defined below). Assume the meanings of access characters are as follows: r: Read access. w: write access. m: management. e: Execute. Then the group s may be understood as the administrator's group. The interesting part of the scheme is that you can assign the meaning of each character in the access string as long as it matches to the required Operation Rights. Each user is assigned a user group when an account is created. The SQLData server uses the granted access rights of the group to determine if a request should be honored or not. There are some predefined user groups in the server configuration file. More groups can be defined as needed.
String. Operation right defines credential required for an operation. Suppose updating server configuration file requires read (r), write (w), execute (e) and management (m) rights, then the Operation Rights can be defined as: @UpdateConfig = rwem A user must be in a group whose credential covers all the required operation rights for the request to be honored. The order of each character in the string is insignificant. Note that the credential or a group doesn't need to match the operation rights exactly. For instance, if group x has the following right, @x = rewmnf Then, users in the group are able to update the configuration because they have more credentials than required.
The servers shipped with some predefined operation rights that cover most of the operations. You will need to adjust the user group settings if you change these parameters.
String. The setting specifies the user information file. The file contains information, such as user name, password, user group, etc. The default user file is sqldata.usr under the config subdirectory. Each user in the user information file is encrypted, and the whole file is validated using a digital digest. You should never modify the file using a text editor.
The server support management functions, which allows administrator to add, delete users from the user file. Refer to the server user guide for further details.
The following is the content of the configuration file shipped with the version 2.0 server. [system] ;set to 1 for password , 0 for none Authentication=1 UseSession=0 ;legal machine ValidIP =* ;illegal machine InvalidIP = ;the default data source DataSource=TestDbase ; the name of the debug file; debugmmddyy.log is used if not specified ; DebugFile=debug.log ; the name of the logging file; logmmddyy.log is used if not specified ; LogFile = mylog.log ; using thread if MultiThread is true MultiThread = true ;max number of cached message handlers MaxHandler= 50 ;Code markers ;MarkerStart= <!-- ;MarkerEnd = --> MarkerStart= [ MarkerEnd = ] ;max rows requested in httpbroker MaxRows= 200 ; the license file name License=stone.lic ;protocol used by RPC service [Security] ;server certificate, complete path. ;SSL will be enforced if this is set. ;ServerCertificate= test.pem SSLVersion = 23 ;colon separated list of cipher name , or use DEFAULT, SSLv3 ;Ciphers= RC4-MD5:EXP-RC4-MD5:CBC-IDEA-MD5:CBC-DES-MD5:CBC3-DES-MD5:CFB-DES-M1 Ciphers =SSLv3 ;a file contains a list of CA certificates, must be in the certs directory CAlist = server.pem ;Secret password for between server communications ;Messages are encrypted using the secret. ;All servers in the cluster must share the same secret ;in order to talk to each other. The secret should ; start with '@' char. ServerSecret=@TheCoolDatabaseService ; use proxy, the following setting contain both host and port ; like www.microsoft.com:9000 ; Proxy=callandor1.erols.com:80 ; proxy=rock:8080 ; file contains user info., relative to config dir UserFile=sqldata.usr ; The server that is responsible for authentication ; used in clustered operation for centralized login. ;AuthServer=stone:8732 [MessageFilter] ; full path of libraries separated by space, which implement filter function InMessageFilters= OutMessageFilters= [Notification] ; do not define Mail Server if no notification is needed. MailServer = smtp.erols.com SenderAddress=yzhang@erols.com Subject= Database Error Recipients= yzhang@erols.com [Cluster] ;Membership of the server in the cluster ; 0 - none 1 - broadcastonly, 2 -receiveonly, 3 -broadcast and receive ClusterMember=3 ; UDP group address, must be class D, 224.0.1.0--239.255.255.255 UDPAddress=234.7.6.5 UDPPort=6773 ; UDP multicasting interval in milliseconds UDPTimer=6000 ;if RPCService is set to 1, RPC Service will be enabled. RPCService=1 ;network protocol for RPC, default is ncacn_ip_tcp ;see RPC guide for details ;RPCProtocol=ncacn_ip_tcp ;Partners for this primary server, a complete url spec ;Partners = rpc://host1:port;uda://host2:port/NetServer [VirtualPath] ; root directory, all others are relative to this one ;Root =\sqldata2.0 DocRoot=htdocs /Admin=htdocs/admin /Images=htdocs/images /Include=htdocs/include /template=htdocs/template ; directories that contains template files, separated by ';' ; they are relative to the virtual dir TemplateDir=template;.; ;Interpret URL using this template URLTemplate=/Action/DataSource/SQLStatement/RowId DefualtPage=home.html
[MsgHandler] ; format $Request=LibraryName@Function ; Function is optional $DBManager=dbextern.dll [ErrorPages] ; format : string Error followed by error number Error400=error.html Error401=error.html Error402=error.html Error403=error.html Error404=error.html Error405=error.html Error406=error.html ; access rights definition ; r : read w : write e : execute m : management ; char @ is prefixed to avoid symbol collision [UserGroup] ;Administrator r-read w-write e-execute m-manage s-system @s=rwem ;Operator @o=rw ;normal user @u=rw ; system maintenance @m=rws [OperationRights] ; rights associated with operations @ShowFile= r @Query= r @RecordQuery= r @AdminQuery= rwe @BrowseQuery= r @SQL= e @ShowTables= r @Insert= e @Update = w @Delete = e @Browse = r @AddForm = e @Detail = r @Display = r @GetCA = r @GetCertificate=r @FindObject = r @GenerateHTML = ew @UpdateConfig = rwem @Admin = rwem @ChangePassword = r @ExportTable=rws @CopyTable=rws @CopyDataSource=rws |
Send mail to info2-at-sqldata-dot-com with questions or comments about
this web site.
|
