KCML System Configuration
This page is used to configure KCML based Software by changing the settings in the kconf.xml configuration file. Although many of the links are available to any Valid User, only Admin Users can make any changes.
The first two links are directory listings for the KCML directory and the WebServer's root directory, $KCMLDIR/kwroot. Next are a table of links for inspecting and changing settings in the various sections of the kconf.xml configuration file.
| Link | Purpose |
|---|---|
| General Environment | Environment variables common to all services |
| Services and their environments | Add/Remove a service or change a service's environment variables |
| Valid users and their environments | List of users who are allowed to access the WebServer |
| Admin users | List of users who are allowed to make changes using the WebServer |
| Valid clients and their environments | List of IP addresses and machine names who are allowed to access the WebServer |
| Web Aliases | Look-up table for aliasing URL's to filenames and directories |
| Connection Policy | Global connection policy. |
| Web Services | Look-up table for matching a client to a server program |
| Table spaces | Default directory for a service's database files |
| Update kconf.xml | Directly edit kconf.xml |
This section stores a table of environment variables which are common to all services, valid clients and valid users.
Typical examples of environment variables that are stored in this section are:
| Variable | Default value | Purpose |
|---|---|---|
| WEBSERVER | true | Enables/disables access to the WebServer from a Web Browser, the Connection Manager is still enabled |
| WEBADMIN | true | Enables/disables the WebServer's Administration functions |
| PATH | Machine dependent | List of directories to search when executing a command. |
Setting variables in this section has a global effect. However, values can be overridden by resetting variables to different values in the environment blocks of the Valid User, Valid Clients, or Services sections.
Important Note: Care must be taken when setting the PATH variable, especially on Unix systems. As KWebServ is started via the network daemon, inetd, then it will not inherit any environment variables that are set via /etc/profile for a telnet login. This means that PATH must be initialised in kconf.xml, it cannot self-reference.
For example: PATH=$PATH:/myapp/bin would result on a PATH value of :/myapp/bin
When kconf.xml is installed the PATH environment variable is taken from the shell.
This section describes the various applications the connection manager can provide. A service has the following properties:
The Name is the name of the service. It is a common reference used by the WebServer, KClient and the KCML ODBC Server.
The Type property describes what type of database files the service will use.
The Connection property allows/disallows KClient to connect.
The Catalogue is the name of the database catalogue file which is also used by the KCML ODBC Server.
A service can define its own Connection Policy which will override any global connection policy.
A brief description can be entered into the Description field.
The Default tablespace property is default directory where the application stores its database files.
The list of directories the service will store its database tables can be specified in the Table Space list
The Global ID property is used to identify the service. This should be not be set for applications that use a global process which will use the global's partition number instead.
The KCML type property controls the compiler that is executed by kmake.
The SOAP services is a list of SOAP interfaces that the service can provide.
A Startup script can be defined for use with kwebserv -i in a boot script.
The Catalogue is a database table containing the list of data files that the service uses.
The service can have an Environment block. This should contain application specific environment variables.
Typical examples are:
| Variable | Purpose |
|---|---|
| BASE | The location of the application |
| START | Filename of the KCML program to execute when connecting with KClient. |
| PANICDIR | Directory containing KCML Panic files |
| SCREENDIR | Directory containing KCML Screen dump files |
| SYSTEMID | Multiple ASP environment identifier |
| TERMFILE | The location of the KCML terminal table. |
| UMASK | Unix only. File creation mask, eg 022. |
Expressions can also be used for the value of an environment variable. The format of the expression is:
${VAR-defaultValue}
If $VAR is set then the expression evaluates to the value of $VAR.
If $VAR is not set, then the expression evaluates to defaultValue.
The default value can either be a constant or another environment variable.
For example:
${COLOR-blue}
${HOMEDIR-$HOME}
In addition to the names of environment variables, files can be included by using the get_include, try_include or include directives. The include directive will load environment variables from an XML document.
The get_include directive will load the environment from a plain text format file.
The format of each line is:
[UNB]"VAR","value"
The first character of a line in this file determines what platform the variable applies to. It can take the following values.
| Character | Meaning |
|---|---|
| U | Set variable on Unix platforms only |
| N | Set variable on Windows platforms only |
| B | Set variable on both types of platforms |
If the first character of a line is a '#' character, then the line is treated as a comment and ignored.
The get_include and include directives will report an error if the file could not be loaded, eg:
Cannot find include file for service 'myApp': Failed to open include file '/user1/myapp/stdenv.xml'
The try_include directive, which will load both XML and text files, will not report an error.
Note: From 6.20 onwards environment variables can be used in the pathnames for the location of table spaces, database catalogues, and the include directives.
The Connection Manager can define three types of Access Control Lists (ACLs) that can be used to restrict access.
Each entry in an ACL is either a name or a KI_PMATCH pattern, such as fred*. Names should be at the top of the list, patterns should be at the end.
Most ACLs are inclusive: if match is found in the list then access is granted. However, with 6.20 onwards, ACLs can also be exclusive: names or patterns which are prefixed by ! are not allowed.
Access can be restricted to all of the Connection Manager's resources by defining ACLs to the top-level, these are maintained by the links on the KCML System Configuration page.
Each service can also define its own private ACLs, these lists are checked after the top-level ACLs. This is particularly useful when using the Connection Manager in an ASP environment as access to a service can be restricted to a specific set of users or network addresses. If a service doesn't define any of its own access control lists, then access is only restricted by the top-level ACLs.
From 6.20 onwards, the access control lists can be defined in an include file. Add a username or IP address of include followed by the pathname of the include file. This file is an XML document, and is has similar layout to kconf.xml.
When access is not allowed by the list an appropriate error message is reported back to KClient. However, when using a web browser, most errors are reported as a "401 authentication" error. The error is always reported to the host's system log.
This is an access control list of user names, or patterns such as fred*. When a user is authenticated they are checked against this list after being verified against the system's password database. On Unix system's the account's home directory is also checked for the existence of a .kcmlLogin file. Each valid user can have their own environment block. The Current service is stored in this block as the SERVICE variable.
This is a list of user names, or patterns, of users who can make changes to the settings stored in the kconf.xml configuration file using the WebServer's administration functions. Users who are not in this ACL, but have WEBADMIN set to allow them access to the administration functions are only granted read-only access.
This is a list of machine names, IP addresses, IP address patterns or Variable Length Subnet Masks. When a connection is made to the Connection Manager it will check the peer address of the client. If the network address is in this list, or it matches one of the IP address patterns or masks then access is granted.
The default, top-level, entries are localhost and a pattern which allows access to all machines on the host server's subnet. For example if the host server has an IP address of 1.12.23.34, then the pattern will be 1.12.23.* .
Machine names are supported, but will require a DNS lookup to resolve the network address. Variable Length Subnet Masks (VLSM) are also supported, eg 11.22.33/24. Patterns of machine names, such as fred* and domain names, eg *.sales.mydomain.com, are not supported.
A valid client can also have an Environment block. For example, setting the WEBADMIN environment variable can enable or disable the WebServer's Administration functions for that machine-name, IP address or IP address pattern/mask. Setting the WEBSERVER environment variable can enable or disable access to Web-Browser for specific valid clients
Important Note:The localhost entry should not be removed at it is used by the Remote licence daemon. If this entry is removed, the licence daemon will refuse connections from the WebServer and many of the links on the KPrint & KMail Remote Licensing page will fail to work.
When configuring kconf.xml for the first time, when large number of new users may be being added to the system, it may be useful to use the kconf utility to import access control list data from a text file.
Connection Manager,
Connecting to a Service,
Remote Adminstration Functions,
Connection Errors