Administration Server Directives and Error Messages: IBM HTTP Server
System Administration IBM HTTP Server documentation

Administration Server Directives and Error Messages


Administration Server Directives

<AdminRoot> section

  • Description - Defines the configuration files of the target server, which is the IBM HTTP Server that the Administration Server is configuring. Each <AdminRoot> section refers to a unique set of configuration files for the target server. At least one <AdminRoot> section is required in the Administration Server configuration file. A target configuration is identified by its ServerRoot and configuration file. It is valid to have more than one <AdminRoot> directive with the same root argument, since several top-level configuration files can exist under one ServerRoot directory. A number of additional directives apply to <AdminRoot> sections. The scope of these directives is limited to the <AdminRoot> section in which they are declared.
  • Scope - Server configuration
  • Usage - <AdminRoot server_root> ... </AdminRoot>
       <AdminRoot "/usr/local/apache">
          AdminAlias "My Favorite Server"
          TargetServerRoot "/usr/local/apache"
          TargetServerConfig conf/httpd_test.conf
          TargetAdminAllowDir /usr/local/apachea
          AdminAllowDir /usr/local/apacheb deep
       </AdminRoot>
    
  • Notes - If server_root is not specified, an error occurs.

AdminAlias

  • Description - Specifies an alias for the target server. If no AdminAlias is declared in an <AdminRoot> section, the value defaults to the fully qualified path name of the top level configuration file for the target server.
  • Scope - Server configuration
  • Usage - AdminAlias <server_alias>
  • Default - Fully qualified pathname of the value specified by the TargetServerConfig directive in the <AdminRoot> section.

AdminAllowDir

Updates to "Directories that configuration can access", on Getting Started >Manage Servers generate an AdminAllowDir subdirective of AdminRoot. This directive controls directory access within the Administration Server GUI. The Administration Server allows access to files and directories specified in the AdminAllowDir subdirective of AdminRoot.

  • Description -Declares which directories are viewable by the browsing capabilities of the Administration Server. The "deep" option allows browsing access to subdirectories of the AdminAllowDir directory. If browsing to subdirectories is not permitted, you can specify the "shallow" option.
  • Scope - Server configuration
  • Usage - AdminAllowDir <directory> [deep | shallow]
  • Default - If this directive is not specified, directory or file browsing access is not allowed. If "deep" or "shallow" is not specified, the default is "shallow".

TargetAccessConfig

  • Description - Specifies the path of the top level access configuration file of the target server You can specify an absolute or relative path. If specified as a relative path, the ServerRoot specified in the <AdminRoot> section is considered the root directory.
  • Scope - Server configuration
  • Usage - TargetAccessConfig <file_path>
  • Default - conf/access.conf

TargetResourceConfig

  • Description - Specifies the path of the resource configuration file for the target server. You can specify an absolute or relative path. If specified as a relative path, the ServerRoot specified in the <AdminRoot> section is considered the root directory.
  • Scope - Server configuration
  • Usage - TargetResourceConfig <file_path>
  • Default - conf/srm.conf

TargetServerConfig

  • Description - Specifies the path of the top level configuration file for the target server. You can specify an absolute or relative path. If specified as a relative path, the server_root parameter specified in the <AdminRoot> section is used as the root directory.
  • Scope - Server configuration
  • Usage - TargetServerConfig <file_path>
  • Default - conf/httpd.conf

Administration Server Error Messages

Request failed! Check log(s).

There was a runtime error while starting or restarting the IBM HTTP Server.

  1. Check the Administration Server error log, admin_error.log, for possible causes. Go to Getting Started >View Admin Logs
  2. Go to Logs > View Logs. Check the IBM HTTP Server error log (error.log) for possible causes.
  3. Try starting IBM HTTP Server as a process: apache -f <configfile>. When starting IBM HTTP Server as a service, net start, some runtime errors are suppressed. You may only get an error that states "Service could not be started", without additional details.

Restart of target server failed.

Check the messages returned from the server. If the message indicates that perhaps a directive is misspelled, or a module is missing, you can assume that the module processing the directive is not loaded. Here is an approach to detect which module needs loading:

  1. Go to View Configuration > Directive Index, find and select the directive name; the task where that directive is set displays.
  2. Check the return message next to the bullhorn on top, to see if any required modules for the page are missing.
  3. Turn on Help if unloaded modules are listed in the return message and select entries on the page, until the missing directive name appears at the bottom of the page. After the directive name, the name of the module processing that directive is listed.
  4. Click on the module name in the return message, if this module is one of the modules listed in the return message. The Administration Server displays the Module Sequence page. You can either load the needed module, or unset the directive setting, so that the restart error does not appear.
  5. Restart the server.

Configuration file has failed a syntax check.

Check the messages returned from the server. The name of the directive and the nature of the syntax error are described. To locate where the directive is set and correct the error:

  1. Go to View Configuration > Directive Index, find and select the directive name; the task where that directive is set displays.
  2. Turn on Help and select entries on the page until the directive name appears in the Help area, at the bottom of the page.

    Note: Some directive settings span more than one entry field.

  3. Make the necessary corrections in the entry field(s) where the directive is set.
  4. Restart the server.

Scope has invalid parent scope.

A scope is contained within an invalid parent scope. Scopes are organized as a hierarchical structure, and have the following valid hierarchical relationships:

  • <Global>
    • <SNMP>
    • <Limit>
    • <Files>
    • <Files Match>
      • <Limit>
    • <Location>
      • <Limit>
    • <Location Match>
      • <Limit>
    • <Directory>
      • <Files>
      • <Files Match>
      • <Limit>
    • <Directory Match>
      • <Files>
      • <Files Match>
      • <Limit>
    • <Virtual Host>
      • <Location>
      • <Location Match>
      • <Directory>
      • <Directory Match>
      • <Files>
      • <Files Match>
      • <Limit>

Invalid directory path specified.

The directory path specified cannot be located, or cannot be parsed as a directory path.

Applies to AIX
Applies to HP Applies to Linux Applies to Solaris

Error code received when attempting to open file.

This error can result because the file either does not exist, or you do not have access permission. In addition to the access allowed within the Administration Server, your operating system may require directories and file permissions.   See File Permissions, if running on AIX, HP, Linux, or Solaris, for more specific information.

The Administration Server user settings do not permit access to file.

The file you have attempted to access does not reside within a directory specified for access by the Administration Server. In Getting Started > Manage Servers, you can specify which directories in your file system are accessed by the Administration Server.

Note: These settings are separate from any required operating system access permissions.

Applies to AIX
Applies to HP Applies to Linux Applies to Solaris

Error writing file. 'Write' access may not have been granted.

In addition to the access allowed within the Administration Server, required directories and file permissions may exist.   See File Permissions, if running on AIX, HP, Linux, or Solaris, for more specific information.

Incompatible task and scope combination.

Tasks are organized into associated directive settings that are valid within defined scopes. The following is a list of valid scopes for each task. (Tasks that are not constrained by scope are not listed.)

Task Name   Valid Scope(s)
Basic Settings
Core Settings:   <Global>, <Virtual Host>
Advanced Properties:   <Global>
Server Options:   All scopes except <Limit> and <SNMP>
Headers:   All scopes except <Limit> and <SNMP>
Cache Expiration:   All scopes except <Limit> and <SNMP>
Module Sequence:   <Global>
Additional Files:   <Global>
Machine Translation:   All scopes except <Limit> and <SNMP>
Meta Headers:   All scopes except <Limit> and <SNMP>
 
Indexing
Options:   <Global>, <Virtual Host>, <Directory>, <Directory Match>
Files:   <Global>, <Virtual Host>, <Directory>, <Directory Match>
Icons:   <Global>, <Virtual Host>, <Directory>, <Directory Match>
File Descriptions:   <Global>, <Virtual Host>, <Directory>, <Directory Match>
Icon Descriptions:   <Global>, <Virtual Host>, <Directory>, <Directory Match>
 
General Access
General Access:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>, <Limit>
Individual Access:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>, <Limit>
Group Access:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>, <Limit>
Other Access:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>, <Limit>
Anonymous Access:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>, <Limit>
 
Security
Server Security:   <Global>
Host Authorization:   <Virtual Host>
Directory Authorization:   <Directory>, <Directory Match>
Certificate Revocation List:   <Global>, <Virtual Host>
Cryptographic Accelerator:   <Global>, <Virtual Host>
 
Logs
Main Logs:   <Global>, <Virtual Host>
Other Logs:   <Global>, <Virtual Host>
Directory Logging:   All scopes except <Limit> and <SNMP>
View Logs:   <Global>, <Virtual Host>
 
Mappings
Messages:   All scopes except <Limit> and <SNMP>
Aliases:   <Global>, <Virtual Host>
Redirects:   <Global>, <Virtual Host>
Username Directories:   <Global>, <Virtual Host>
 
Scripts
Associate Actions:   All scopes except <Limit> and <SNMP>
Define Variables:   <Global>, <Virtual Host>
Unset Variables:   <Global>, <Virtual Host>
Conditional Variables:   <Global>
Browser Detection:   <Global>
 
Performance
Server Settings:   <Global>
Set Cache:   <Virtual Host>, <Directory>, <Directory Match>, <Location>, <Location Match>
SNMP:   <SNMP>
 
MIME
MIME Files:   All scopes except <Limit> and <SNMP>
MIME Types:   All scopes except <Limit> and <SNMP>
MIME Encodings:   All scopes except <Limit> and <SNMP>
Document Handlers:   All scopes except <Limit> and <SNMP>
Remove Handlers:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>
Language Files:   All scopes except <Limit> and <SNMP>
Type Handling:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>
 
Fast CGI
Internal Server:   <Global>, <Virtual Host>
Configuration:   <Global>
External Server:   <Global>
Access:   <Directory>, <Directory Match>
 
File Systems
Enable DAV:   <Directory>, <Directory Match>, <Files>, <Files Match>, <Location>, <Location Match>
DAV Settings:   <Global>, <Virtual Host>
 
Proxy
Proxy Cache:   <Global>, <Virtual Host>
Proxy Settings:   <Global>, <Virtual Host>
 
View Configuration
Edit Configuration:   All scopes
 

File browsing is not enabled for any directory.

Directory access has not been specified by the Administration Server. In Getting Started > Manage Servers, you can specify which directories in your file system are accessed by the Administration Server.

Note: These settings are separate from any required operating system access permissions.

Applies to UNIX platforms

File Permissions

In addition to the access allowed within the Administration Server, there are required directories and file permissions for normal UNIX System Administration.

The IBM Administration Server derives its file permissions for each request from the User and Group directives, in the Administration Server Configuration File, admin.conf.

  • Any directory that you allow access through the AdminAllowDir directive, must also have at least read access file permissions for the user ID, or Group in the Administration Server configuration file, admin.conf.
  • For those files, or directories that contain configuration files, for example /conf, httpd.conf, or admin.conf, ensure that the Administration Server user ID or Group has read and write access file permissions.
  • For those files, or directories that contain User Authentication files or Group Authentication files, ensure that the Administration Server user ID or Group, has read and write access file permissions.

Applies to AIX
Applies to HP Applies to Linux Applies to Solaris

Setupadm Script

The setupadm script establishes permissions for configuration file updates. After a default server installation, updates to the configuration files are not possible, unless this script is run, or the user sets permissions manually.

The setupadm script prompts you for input. See below:  

  • Prompts:
    • User ID
      The user ID under which the Administration Server runs. This user ID is created from this script.
    • Group Name
      The Administration Server accesses the configuration files and authentication files through the Group file permissions. The specified group is created through this script.
    • Directory
      The directory in which configuration files and authentication files are located.
    • File Name

      These file groups and file permissions change:

      • Single File Name
      • File Name with WildCard
      • All (Default) - all files in the specific directory.
    • Processing:

      The objective of the setupadm script is to change the Group and File permissions of the configuration files and authentication files.

      It is necessary for the Administration Server to have read and write access to configuration files and authentication files to perform administration of Web server configuration data.

      It is necessary for the Administration Server to execute adminctl restart as root, to perform successful restarts of the Administration Server and the IBM HTTP Server.

Applies to UNIX

Setting Permissions Manually

To Create a new user and group for the Administration Server:

Applies to AIX

On AIX:

  1. Go to SMIT. Select Security and Users.
  2. Select Groups. Select Add a Group.
  3. Enter the group name (e.g. admingrp). Click OK.
  4. Go back to Security and Users.
  5. Select Users. Select Add a User.
  6. Enter the user name (e.g. adminuser). Enter primary group created above.
  7. Click OK.

Applies to Solaris

On Solaris:

  1. Bring up the admintool.
  2. Select Browse and then select Groups.
  3. Select Edit and then Add.
  4. Enter the Group Name (e.g. admingrp). Click OK.
  5. Select Browse and then select Users.
  6. Select Edit and then Add. Enter the user name (e.g. adminuser) and the primary group name (e.g. admingrp). Click OK.

Applies to HP-UNIX

On HP:

  1. Execute groupadd <groupname>, from the command line.
  2. Execute useradd -g <groupname> <userid>.

Applies to Linux

On Linux:

  1. Execute groupadd <groupname>, from the command line.
  2. Execute useradd -g <groupname> <userid>.
  1. Update the group and file permissions for the configuration file of the IBM HTTP Server (httpd.conf).
    1. Go to a command prompt and change the directory that contains the httpd.conf file.
    2. Type the following commands:
      
      - chgrp <groupname> httpd.conf 
      - chmod g+rw httpd.conf
  2. Update the file permission for the configuration file of the IBM Administration Server (admin.conf).
    1. Go to a command prompt and change to the directory that contains the admin.conf file.
    2. Type the following commands:
      
      - chgrp <groupname> admin.conf 
      - chmod g+rw admin.conf
  3. Update the file permission for all the other IBM HTTP Server configuration files.
    1. Go to a command prompt and change to the directory containing configuration files:
      • access.conf (if used)
      • srm.conf (if used)
    2. Type the following commands:
      
      - chgrp <groupname> <filename>
      - chmod g+rw <filename>
  4. Update the configuration file for the Administration Server (admin.conf)
    1. Change to the Administration Server admin.conf directory.
    2. Search for the following lines in the admin.conf file:
      - User nobody
      - Group nobody
    3. Change these lines to reflect the user ID and group name you created:
      - User user ID
      - Group groupname
  5. Start the Administration Server by typing ./adminctl start in the user/HTTPServer/bin directory.
  6. Select Manage Servers to define the servers you wish to administer from the Administration Server
  7. Start the IBM HTTP Server by typing ./apachectl start in the user/HTTPServer/bin directory.
 
Related information...

     (Back to the Top)