Using administration server directives and identifying error messages

This section provides information on using the Administration Server directives and identifying error messages. Links to related information appear at the end of this section.

• Using administration server directives
• <AdminRoot> section
• AdminAlias
• AdminAllowDir
• TargetAccessConfig
• TargetResourceConfig
• TargetServerConfig
• Identifying administration server error messages
• Generic success message
• Server restart messages
• Target configuration file errors
• Read and write errors
• Problems in the cfgdata dispatch table
• Problems with user input
• Internal errors
• Granting file permissions
• Running the setupadm script
• Finding related information

Using administration server directives

The following section provides details on the Administration Server directives, including directive descriptions, defaults, scopes, syntax and associated notes .

<AdminRoot> section

• Description: Defines the configuration files that the Administration Server configures of the target, or IBM HTTP Server. Each <AdminRoot> section refers to a unique set of configuration files for the target server. The administration server configuration file requires at least one <AdminRoot> section. The ServerRoot directory and configuration file identify a target configuration. You can 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. These directives have scopes limited to their declared <AdminRoot> sections.
• Default: server_root
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: <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>
  

  An error occurs if you do not specify server_root.

• Values: Path to the root directory.

AdminAlias

• Description: Specifies an alias for the target server.
• Default: Fully qualified path name of the value specified by the TargetServerConfig directive in the <AdminRoot> section.
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: AdminAlias <server_alias>
• Values: If you do not declare an AdminAlias in an <AdminRoot> section, the value defaults to the fully qualified path name of the top level configuration file for the target server.

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 viewable directories through the browsing capabilities of the administration server. The deep option enables browsing access to subdirectories of the AdminAllowDir directory. If you cannot browse subdirectories, you can specify the shallow option.
• Default: If you do not specify this directive, then you do not have directory or file browsing access. If you do not specify deep or shallow, the server defaults to shallow.
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: AdminAllowDir <directory> [deep | shallow]
• Values: Path to the viewable directories in the server.

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 server considers the ServerRoot specified in the <AdminRoot> section as the root directory.
• Default: conf/access.conf
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: TargetAccessConfig <file_path>
• Values: Path to the access configuration file.

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.
• Default: conf/srm.conf
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: TargetResourceConfig <file_path>
• Values: Path to the resource configuration file.

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 uses the server_root parameter specified in the <AdminRoot> section as the root directory.
• Default: conf/httpd.conf
• Module: mod_core
• Multiple instances in the configuration file: Yes
• Scope: Server configuration
• Syntax: TargetServerConfig <file_path>
• Values: Path to the httpd.conf file.

Identifying administration server error messages

This section identifies various server error messages and the appropriate actions to take.

Generic success message

The following is a generic message indicating success: Ready

Server restart messages

Messages relating to server restart follow:

• ADM1202I: Start request has been successfully issued
• ADM1204I: Stop request has been successfully issued
• ADM1206I: Restart request has been successfully issued
• ADM1208W: Stop request ignored! Server is NOT running
• ADM1210W: Restart request ignored! Server is NOT running
• ADM1212W: Start request ignored! Server is already RUNNING
• ADM1214E: Start request failed! Check error logs (See details)
• ADM1216E: Stop request failed! Check error logs (See details)
• ADM1218E: Restart request failed! Check error logs (See details)
• ADM1220E: Request not complete. Syntax error in configuration file '%s'. (See details)
• ADM1221I: Please wait while the Administration Server is restarted.
• ADM1222E: Restart request to target server failed. (See details)
• ADM1224E: Restart of Administration Server failed."
• ADM1226E: Configuration file '%s' has failed a syntax check. (See details)

Target configuration file errors

Messages relating to the target configuration file follow:

• ADM1228E: Line %d in file '%s' exceeds maximum line length of %d characters.
• ADM1230E: Syntax error in file '%s' on line %d.
• ADM1232E: Invalid blank line found in file '%s' on line %d. Blank lines may not follow a continuation character.
• ADM1234E: Invalid continuation character syntax found in file '%s' on line %d.
• ADM1236E: Scope has invalid parent scope in file '%s' on line %d. (See details)
• ADM1238E: No matching end tag found for scope <%s...> in file '%s' on line %d.
• ADM1240E: String exceeds maximum buffer size of %d characters in file %s on line %d.
• ADM1242E: Invalid scope type <%s...> found in configuration file.
• ADM1244E: Administration Server internal error detected concerning scope type <%s...>.

Read and write errors

Messages relating to read and write errors follow:

• ADM1246E: Invalid directory path "%s" specified. (See details)
• ADM1248E: Error code %d received when attempting to open file "%s". (See details)
• ADM1250E: The Administration Server user settings do not permit access to file "%s". (See details)
• ADM1252E: Error reading line %d in file "%s".
• ADM1254E: Error code %d received when attempting to obtain status information on file "%s".
• ADM1256E: File "%s" has changed on disk since last update.
• ADM1258E: Error code %d received when writing to file "%s".

Problems in the cfgdata dispatch table

Messages relating to problems in the cfgdata dispatch table follow:

• ADM1260E: Invalid display arguments '%s' specified for field '%s'.
• ADM1262E: Invalid write arguments '%s' specified for field '%s'.
• ADM1264E: Invalid directive name '%s' passed to function.
• ADM1266I: The following modules are not currently loaded: %s.

Problems with user input

Messages relating to problems with user input follow:

• ADM1268I: Incompatible task and scope combination. (See details)
• ADM1270I: The root scope cannot be duplicated.
• ADM1272I: The duplicate scope %s already exists.
• ADM1274I: The root scope may not be moved.
• ADM1276I: No scope name was specified.
• ADM1278E: Invalid data '%s' passed back in variable '%s'.

Internal errors

• ADM1280E: Administration Server internal error: Error parsing query string.
• ADM1282E: Administration Server internal error: Invalid query string syntax.
• ADM1284E: Administration Server internal error: Invalid variable name '%s' specified in query string.
• ADM1286E: Administration Server internal error: Unable to get scope '%s'
• ADM1288E: Administration Server internal error: No AdminRoot scope specified in Administration Server configuration file.
• ADM1290E: Administration Server internal error: Invalid scope identifier '%d' specified for directive search.
• ADM1292E: Administration Server internal error: Unexpected empty data string.
• ADM1294E: Administration Server internal error: Invalid directive '%s' passed to function.
• ADM1296E: Administration Server internal error: Number of arguments exceeds maximum limit of %d, starting with token '%s'.
• ADM1298E: Administration Server internal error: Invalid array syntax in data returned from form.
• ADM1300E: Syntax error in path '%s' returned from form.
• ADM1302E: File browsing is not enabled for any directory. See details
• ADM1304E: Administration Server internal error: Error code %d received when attempting to create a pipe.
• ADM1306E: Invalid installation root path specified for "%s". Correct the error by specifying the path where the apache server is installed.
• ADM1308E: Administration Server internal error: Error code %d received when attempting to fork a process.
• ADM1310E: Error code %d received when attempting to duplicate a file descriptor.
• ADM1312E: Error occurred reading request information.
• ADM1314E: Cookies are disabled on your browser.

Request failed! Check log(s).

A run-time error occurred 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 the IBM HTTP Server as a process: apache -f <configfile>. Starting the IBM HTTP Server as a service, using net start, can suppress some run-time errors. An error stating that Service could not start can display without additional details.

Restart of target server failed.

Check the messages returned from the server. If the message indicates a possible directive misspelling, or a missing module, you can assume that the module processing the directive has not loaded. The following approach detects which module needs loading:

1. Go to View Configuration > Directive Index, find and select the directive name; the task displays where you can set that directive.
2. Check the return message next to the bullhorn on top, regarding required modules for the page.
3. Turn on Help, if you see unloaded modules listed in the return message. Select entries on the page, until the missing directive name appears at the bottom of the page. The name of the module processing each directive displays next to the directive name.
4. Click on the module name in the return message, if you see this module listed in the return message. The Administration Server displays the Module Sequence page. You can either load the required 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 for descriptions of the directive, name, and the nature of the syntax error. To locate where you set the directive and correct the error:

1. Go to View Configuration > Directive Index, find and select the directive name; the task where you set that directive 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.
3. Make the necessary corrections in the entry fields where you set the directive.
4. Restart the server.

Some directive settings span more than one entry field.

Scope has invalid parent scope.

A scope exists in an invalid parent scope. Scopes have a hierarchical structure, with the following valid 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 server cannot locate the specified directory path, or cannot parse this path as a directory path.

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 can 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 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 have access by the Administration Server.

These settings remain separate from any required operating system access permissions.

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 can 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. A list of valid scopes for each task follows. This list only includes tasks constrained by scope.

File browsing is not enabled for any directory.

The Administration Server has not specified access to any directories. Go to Getting Started > Manage Servers, to specify directory access in your file system by the Administration Server.

These settings remain separate from any required operating system access permissions.

Granting file permissions

In addition to the access allowed within the Administration Server, directory and file permission requirements exist 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.

Running the setupadm script

The setupadm script establishes permissions for configuration file updates. You cannot update the configuration files after a default server installation, unless you run the setupadm script, or you set permissions manually.

The setupadm script prompts you for input. See below:  

• Prompts:
  • User ID
    The user ID under which the Administration Server runs. The script creates this user ID.
  • Group Name
    The Administration Server accesses the configuration files and authentication files through group file permissions. The script creates the specified group through this script.
  • Directory
    The directory where you can find configuration files and authentication files.
  • File Name

    These file groups and file permissions change:

    • Single file name
    • File name with wildcard
    • All, the default - all files in the specific directory
  • Processing:

    The setupadm script changes the group and file permissions of the configuration files and authentication files.

    The Administration Server requires read and write access to configuration files and authentication files to perform Web server configuration data administration.

    The Administration Server has to execute adminctl restart as root, to perform successful restarts of the Administration Server and the IBM HTTP Server.

Setting permissions manually

To create a new user and group for the Administration Server, follow these steps, noted by platform:

On AIX:

1. Go to SMIT. Click Security and Users.
2. Click Groups > Add a Group.
3. Enter the group name, for example, admingrp. Click OK.
4. Go back to Security and Users.
5. Click Users > Add a User.
6. Enter the user name, for example, adminuser. Enter the primary group created above.
7. Click OK.

On HP:

1. Execute groupadd <group name>, from the command line.
2. Execute useradd -g <group name> <user ID>.

On Linux:

1. Execute groupadd <group name>, from the command line.
2. Execute useradd -g <group name> <user ID>.
3. 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 <group name> httpd.conf 
      - chmod g+rw httpd.conf
      

4. 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 <group name> admin.conf 
      - chmod g+rw admin.conf
      

5. 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> <file name>
      - chmod g+rw <file name>
      

6. Update the configuration file, admin.conf, for the Administration Server.
   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
      

7. Start the Administration Server by typing ./adminctl start in the user/HTTPServer/bin directory.
8. Click Manage Servers to define the servers you wish to administer from the Administration Server
9. Start the IBM HTTP Server by typing ./apachectl start in the user/HTTPServer/bin directory.

On Solaris:

1. Bring up the admintool.
2. Click Browse > Groups.
3. Click Edit > Add.
4. Enter the group name, for example, admingrp. Click OK.
5. Click Browse > Users.
6. Click Edit > Add. Enter the user name, for example, adminuser and the primary group name, for example, admingrp.
7. Click OK.

     (Back to the top)