eCo Software Developer Connection

eCS File and Directory Standard (eFDS)

Version 1
2003 May 18
Edited by Nick Morrow
Approved for release by Mensys on 2003 May 18

SUMMARY

This standard consists of a set of requirements and guidelines for file
and directory placement under the eCS operating system. The guidelines
are intended to support interoperability of applications, system
administration tools, development tools, and REXX or batch scripts as
well as greater uniformity of documentation. This standard is written
with simplicity and ease of use in mind. This document should not be
expected to answer all questions at this point as it is a work in
progress. You, the eCS user and developer are invited to provide
feedback concerning this document. Please contact your eCS supplier
with comments concerning this document.

1. Introduction

1.1. Purpose

This standard enables

Software to predict the location of installed files and
directories, and

Users to predict the location of installed files and
directories.

We do this by

Specifying guiding principles for each area of the
filesystem,

Specifying the files and directories that are required,

Enumerating exceptions to the principles, and

Enumerating specific cases where there has been historical
conflict.

The document is used by

Independent software suppliers to create applications
which are eFDS compliant,

OS maintainers to maintain eFDS compliance, and

Users to understand and maintain the eFDS compliance of a
system.

1.2. Conventions

Components that vary are represented by a description of the contents
enclosed in "" characters.

Optional components are enclosed in "[" and "]" characters and may be
combined with the "" convention.

Variable substrings of directory names and filenames are indicated by
"*".

2. The Filesystem

It is possible to define two independent categories of files:
shareable vs unshareable and variable vs static. There is a simple
and easily understandable logic to understanding the reason for
defining these categories:

Why are we separating directories into shareable and nonshareable?

Primarily for ease of administration. If a system administrator must
search many locations in the file system because of a lack of clear
guidelines or adherance to guidelines then a lot of time is wasted
and the effort is more pron to errors.

Why are we separating directories into variable and static?

We need to take into consideration which directories should be
read-only and which should be read-write. Static directories should
be read only except to the system administrator while variable
directories should be read-write for more users than the system
administrator.

Shareable files are those which can be shared between different
hosts.

Unshareable files are those which are specific to a particular host.

Static files consist of files that do not change without system
administrator intervention. Examples include binaries, libraries,
and documentation.

Variable files consist of files that do change without system
administrator intervention. Examples include data files.

In a networked environment (i.e., more than one host at a site),
there is a good deal of data that can be shared between different
hosts to save space and ease the task of maintenance. If shareable
files are grouped together in a logical manner a significant
reduction in administrator workload can be realized.

In a networked environment, certain files contain information
specific to a single host. Therefore these filesystems cannot be
shared (without taking special measures).

Interspersing shareable and unshareable data in the same hierarchy
makes it difficult to share large portions of the filesystem.

Interspersing variable and static data in the same hierarchy makes
it difficult to implement a data backup plan.

Summarizing chart:

Note: eCS will contain the following minimum directories to meet
eFDS-1 guidelines. Additional root directories will be needed and
used on current releases of eCS due to the requirements of the
supporting OS/2 operating system. The goal is to consistantly
reduce until finally eliminating all directories not listed
below.

shareable

unshareable

static

\programs

\ecs, \etc

variable

\home

\var, \etc

\ecs
- similar to root (/) in Linux
- static, nonshareable files

read-only

will not be made available on the lan

must be located on host system

must be on the boot volume

must be one instance and no more on host system

\etc
- similar to /etc in Linux
- variable and static, nonshareable files

read-write

will not be made available on the lan

must be located on host system

must be on the boot volume

contains variable and static data requiring backup

\home
- similar to /home in Linux
- variable, shareable files

read-write

may be made available on the lan

does not need to be located on the host system

does not need to be on the boot volume

may be more than one instance on host system

contains variable data requiring backup

\programs
- similar to /usr in Linux
- static, shareable files

read-only

may be made available on the lan

does not need to be located on the host system

does not need to be on the boot volume

may be more than one instance on host system

\var
- similar to /var in Linux
- variable, nonshareable files

read-write

will not be made available on the lan

must be located on host system

does not need to be on the boot volume

must be one instance and no more on host system

Note: While there are similarities to the directory system in Linux
one should not view this to mean that eCS is a re-implementation
of Linux. eCS will implement a file and directory structure that
best meets the needs of users and developers.

3. The Boot Volume

3.1 Purpose

The contents of the boot volume must be adequate to boot, restore,
recover, and/or repair the system.

To boot a system, enough must be present on the boot volume to
mount other filesystems. This includes utilities to modify, move
and delete files in order to restore a satisfactory configuration.
Required system utilities shall be contained in the appropriate
directories in \ecs (or for now in \OS2). \ecs must be located on
the boot volume on the host system. \home and \programs are
designed such that they may be located on volumes other than the
boot volume and may, in fact, be located on systems in the network
other that the host system. \var is not required to be located on
the boot volume but it must be located on the host system as the
data contained in /var is non-shareable.

The primary concern used to balance these considerations, which favor
placing many things on the boot volume, is the goal of keeping boot
volume as small as reasonably possible. For several reasons, it is
desirable to keep the boot volume small:

The boot volume contains many system-specific configuration
files. This means that the boot volume isn't always shareable
between networked systems. Keeping it small on servers in networked
systems minimizes the amount of lost space for areas of unshareable
files. It also allows workstations with smaller local hard drives.

Disk errors that corrupt data on the boot volume are a greater
problem than errors on any other partition. A small root
filesystem is less prone to corruption as the result of a system
crash.

Smaller boot volumes permit greater flexibility in system setup
and maintenance to include the use of bootable memory disks, remote
boot volumes, and "universal" boot volumes customised to fit a
particular line of identical systems.

Software must never create or require files or subdirectories in the root
directory. Other locations in the eFDS hierarchy provide more than enough
flexibility for any package.

There are several reasons why introducing a new subdirectory in the root
directory is prohibited:

It demands space on a root partition which the system administrator
may want kept small and simple for either performance or security
reasons.

It evades whatever discipline the system administrator may have set
up for distributing standard file hierarchies across mountable
volumes.

3.2 Requirements

The following directories are required to meet eFDS standards:

\ecs operating system related directories
- unshareable static files

\etc variable data files
- unshareable variable and static files

\home user home directories
- shareable variable files

\programs application directories
- shareable static files

\var variable data files
- unshareable variable files

3.3 Specific Options

The \ecs directory shall contain the following directories:

\ecs\bin essential command binaries (no subdirectories allowed)

\ecs\book .inf files

\ecs\boot device drivers

\ecs\dll essential shared libraries

\ecs\doc documentation files (contains only subdirectories)

\ecs\help .hlp files

\ecs\install installation files (contains subdirectories)

\ecs\lang national language support

\ecs\system essential system binaries (contains only subdirectories)

NOTE: \ecs\bin and \ecs\system both contain essential binaries but they
are for very different purposes. \ecs\system contains only directories
that hold files related to large complex packages, while \ecs\bin is for
standalone system utilities. There is no implied GUI/CLI split; a CLI
ini file editor and backup program can be a large complex package which
should be located in \ecs\system, while a GUI volume manager could be a
standalone binary located in \ecs\bin.

The \etc directory shall contain the following directories:

\etc\log system and non-user specific application log files

Note: This is a chance since the release of eCS v1.1 which has the
log file directory located as such: \var\log

The \programs directory shall contain only subdirectories which in turn
will contain the files and subdirectories specific to a particular
application. As an example:

\programs\browser would contain the static executable files required to
run an internet browser.

The \home directory shall contain only subdirectories which in turn
will contain the files and subdirectories specific to a particular
user. As an example:

\home\\ would contain the directories which contain variable
configuration and data files created, owned and
maintained by . Another to view this directory
is that if needs to back up his/her work
then this is the only directory he/she should need
to back up.

The \var directory shall contain the following directories:

\var\cache intended for cached data from applications. Such data
is locally generated as a result of time-consuming I/O
or calculation. The application must be able to
regenerate or restore the data. Unlike /var/spool, the
cached files can be deleted without data loss. The data
must remain valid between invocations of the application
and rebooting the system.

\var\spool contains data which is awaiting some kind of later
processing. Data in \var\spool represents work to be
done in the future (by a program, user, or administrator);
often data is deleted after it has been processed.

\var\temp temporary files and directories

Each directory listed above is specified in detail in separate
subsections below.

3.4 \ecs\bin : Essential user command binaries (for use by all users)

3.4.1 Purpose

\ecs\bin contains commands that may be used by both the system administrator
and by users. It may also contain commands which are used indirectly by
scripts or batch files.

3.4.2 Requirements

There must be no subdirectories in \ecs\bin.

\ecs\bin must be included in the SET PATH statement in CONFIG.SYS.

The following commands are required in \ecs\bin.

cpu.exe Utility to report the number of processors installed

mem.exe Utility to report the amount of memory installed

unzip.exe The unzip unarchiving utility

zip.exe The zip archiving utility

Note: This list needs to be updated prior to the next release of this
document.

The requirement for a minumum set of system utilities to perform
various maintenance and troubleshooting functions is vital to the
capability to keep the system operating as desired.

3.5 ecs\boot : Static device driver files

3.5.1 Purpose

This directory contains device drivers with the exception of device
drivers that must be located elsewhere such as BASEDEV drivers which
must be located in "\" or "\os2\boot" in current releases of eCS.

3.5.2 Requirements

Device driver loading:

A clean boot is desirable. Default driver operation will be
Quiet mode (/Q).

There are three situations where a driver may temporarily
pause the boot process and/or post a message:

If registration is pending.

If the driver detects a problem during boot and needs to
post a warning or error message.

If the user tells the driver to post information by adding the
/V (Verbose) parameter to the driver in the config.sys
file.

4. CONFIG.SYS : Host-specific system configuration

4.1 Purpose

CONFIG.SYS contains much of the basic configuration information that is
specific to a system. It is necessary that we define certain mandatory
entries:

SET ETC=X:\etc

SET ETC sets the environment variable ETC so that programs and
utilities may determine the directory to be used for variable
and static system configuration files.

SET TMP=X:\var\temp
SET TEMP=X:\var\temp

SET TMP and SET TEMP set environment variables so that programs and
utility may determine the directory to be used for temporary files.

SET HOME=X:\home\

SET HOME sets the environment variable HOME so that programs and
utilities may determine the directory which is currently designated
as the HOME directory.

SET PROGRAMS=X:\programs

SET PROGRAMS sets the environment variable PROGRAMS so that programs,
utilities and software installers may determine the directory which is
designated as the directory where all non-system programs and
utilities should be installed.

SET LOGFILES=X:\etc\log

SET LOGFILES sets the environment variable LOGFILES so that programs,
utilities and software installers may determine the directory which is
designated as the directory where all log files should be stored.
utilities should be installed.

It is also necessary that we define certain programming guidelines:

Programs/utilities that create log files should check to see if
LOGFILES is set and use it if it is. If LOGFILES is not set or the
directory doesn't exist then log files should not be created. Log
file names should follow this example:

.log - estyler.log

Programs/utilities that use ini files to store user specific
configuration information should check SET USER_INI= and use this
directory to store ini files. Ini files should follow this example:

.ini - estyler.ini

An example of the location:
SET USER_INI=x:\home\stjohnb\etc\user.ini

eStyler would then locate estyler.ini as such:
x:\home\stjohnb\etc\estyler.ini

Programs/utilities that use ini files to store system wide
configuration information should check SET SYSTEM_INI= and use this
directory to store ini files. Ini files should follow this example:

.ini - estyler.ini

An example of the location:
SET SYSTEM_INI=X:\etc\system.ini

eStyler would then locate estyler.ini as such:
X:\etc\estyler.ini

Programs/utilities should always check to see if their ini exists and
if it doesn't exist then a new one with reasonable defaults should be
created. INI files should be standard OS/2 style binary INI files.

Programs/utilities should not make modifications to CONFIG.SYS with
the exception of adding required device drivers nor should they use
the user.ini or system.ini to store settings.