Epoch Init System Configuration Documentation

This is documentation for creating an Epoch configuration file.
If you find it to be incomplete or if it contains errors, please contact Subsentient at thinkingrodent@gmail.com. A sample configuration file is available here. Place it at /etc/epoch/epoch.conf.

Contents


General syntax

Services and options in the Epoch Init System are defined and configured in a single configuration file, /etc/epoch/epoch.conf. The configuration directory can be changed at compile time, but by default epoch.conf goes into an otherwise empty directory, /etc/epoch. Additional configuration files can be imported via the Import attribute. Epoch provides a flexible configuration system with many options, although if you are a die-hard UNIX/POSIX fellow, you may find some things to be unusual. Let's begin with the syntax for a declaration in epoch.conf.

ObjectID objectname

As you can see, it's very straightforward.

The order in which global options are specified in relation to each other is irrelevant, so long as they come before you start specifying ObjectIDs, and the order in which object attributes are specified in relation to each other is irrelevant, so long as you keep in mind that whatever comes after an ObjectID attribute will affect only that object, until another ObjectID attribute is encountered, and then it switches to the new object.

You may use spaces and tabs as the delimiter between the attribute name and the attribute value, or, if you prefer, you can use a single equals sign with no whitespace, like so:

ObjectID=objectname

These two declarations are functionally identical and equally valid. You may of course mix equals-delimited and whitespace-delimited declarations in epoch.conf. It is also legal to use whitespace to pad in front of declarations to create a block structure appearance, like so:

ObjectID objectname
    ObjectDescription Object Name
    ObjectPrestartCommand thing
    ObjectStartCommand thingy
    ObjectStopCommand=PID
    ObjectReloadCommand stuff
    ObjectStartPriority 1
    ObjectStopPriority=1
    ObjectRunlevels turnips
    ObjectOptions=SERVICE TERMSIGNAL=15 FORCESHELL
    ObjectEnabled=true

Guidelines And Tips

There are some general guidelines that you should follow. First, you should make sure that /proc is mounted on boot, and that it's not unmounted on shutdown, since that's not necessary for the root filesystem to unmount. If /proc is not mounted, the advanced PID detection system will not work, reducing accuracy of PID tracking for services greatly, and Epoch will not be able to detect if a service is running unless it uses a PID file, rendering many objects with the AUTORESTART attribute inoperative.

It is also advised that you enable the SERVICE option for services that will continue to run, that "daemonize". If the advanced PID tracking system fails due to /proc not being available, this will assist Epoch in keeping track of the correct PID.

Lastly, avoid declaring too many objects with the same start/stop priorities when possible, because this is simply bad practice and can and probably will eventually cause confusion and mistakes in future edits.

Comments

Single line comments

A single line comment is created by placing a '#' at the beginning of the line. Whitespace may precede the '#'.

Multi line comments

A multi line comment is created as such:

>!> stuff
stuff
stuffy stuff
<!< things
thingy things
thingy things that are thingy

As you can see, anything called stuff will not be processed. anything called things will, however.

Global Configuration

NOTE: Global Configuration attributes should always come before any Object Configuration attributes.

DefaultRunlevel

DefaultRunlevel is used to specify the runlevel used when the system boots up. It's format is "DefaultRunlevel runlevelname". Runlevel names may not contain spaces.

RunlevelInherits

RunlevelInherits is used to mimic the behaviour of merging two runlevels. Say that runlevel 'gui' contains only the display manager, but runlevel 'multiuser' contains everything else. By using 'RunlevelInherits gui multiuser', all objects in 'multiuser' will also be started if we enter runlevel gui, provided they aren't already started.

If, say, 'multiuser' inherits runlevels of it's own, only 'multiuser' will be inherited. This means that there is no recursive inheritance, which is probably good for the sake of safety. Therefore, if 'multiuser' inherits 'core', then to enter 'gui' which inherits 'multiuser' without stopping everything in 'core' first, you must do the following:
RunlevelInherits=gui multiuser
RunlevelInherits=gui core
Whether the statement with 'multiuser' or 'core' is specified first is irrelevant. The effect is the same.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

DefinePriority

DefinePriority is used to assign an ASCII name to a numeric start/stop priority. It's usage is 'DefinePriority ASCIIName 1'. The resulting name can be used for both stop and start priorities. This is useful for grouping services together under one priority. It is, of course, optional.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

DisableCAD

DisableCAD is used to control whether or not Epoch or the system's kernel will control what happens when CTRL-ALT-DEL is pressed. If set to "true", Epoch will control what happens, and pressing CTRL-ALT-DEL during bootup or shutdown will kill the current job being processed. If idle or five seconds have not passed since the last time CTRL-ALT-DEL was pressed (bootup only), then a standard reboot begins. If set to "false", pressing CTRL-ALT-DEL will be handled by the kernel, and this will trigger an instant system restart. Tasks will not be stopped, filesystems will not be unmounted.

BootBannerText

BootBannerText is used to specify an optional MOTD for when the system boots up. You can enter a literal string of text, or you can enter a file location via "FILE /location/file.txt". Color codes are allowed in the file. Be advised that the file's contents, in full, will be dumped to the console.

BootBannerColor

BootBannerColor is used to set a color for the Boot Banner specified by BootBannerText. The value can be one of NONE, BLACK, BLUE, RED, GREEN, YELLOW, MAGENTA, CYAN, or WHITE. Instead of NONE, you can omit BootBannerColor completely.

Hostname

"Hostname" is used to specify the hostname to be used for the system. You may also specify a file to read the hostname from in the format "FILE /etc/hostname". The value must be a valid value for a system hostname. The hostname specified will be set as the system hostname upon boot, before any objects are loaded.

Domainname

Analogous to Hostname, except it specifies the domain name rather than the hostname.
NOTE: Not available in pre-1.1 versions.

MountVirtual

MountVirtual is used to specify virtual kernel filesystems that should automatically be mounted and optionally have their directories created upon boot. This is performed before any objects are loaded. The value may be one or more of "devfs", "devpts", "devshm", "procfs", or "sysfs", and if suffixed with a "+", such as "devpts+", then the directory is created with the appropriate permissions, prior to mounting.

EnableLogging

EnableLogging is simply used to enable or disable the logging system. Valid values are "true" and "false", however logging is disabled by default if this is not specified.

BlankLogOnBoot

If BlankLogOnBoot is set to true, then the log will be blanked on each bootup, so that the log can only ever contain the boot logs of the current boot cycle. This is useful to prevent the log from growing to a massive size and being painful to read to the console. If not specified, the default is "false".
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

GlobalEnvVar

Sets an environment variable that will be applied to all objects. Example: GlobalEnvVar=WIBBLE=Derp herp wibble! Quotes are considered part of the environment variable rather than as a means to enter strings. No quotes are necessary for entering strings.
NOTE: Not available in pre-1.1 versions.

Import

the Import attribute is used to import a configuration file to be loaded. It's used for using more than one configuration files. Since all configuration begins at epoch.conf, at least one Import= will need to be present in that file if you wish to use more than one config file. Imports are recursive and an imported file may import more of it's own. You may specify either an absolute path or simply the name of a config file, which will be loaded from the configuration directory, /etc/epoch/ by default. The effect is much like importing the contents of the specified file into the location of the current configuration file where the attribute is placed, with the exception that objects must be completed within the same file, e.g. ObjectID in one.conf and ObjectEnabled in two.conf is illegal. Because of this, it's illegal to specify global options once an object has been loaded from any configuration file, with the exception of Import and a handful of others. Still, while it's not bad practice to include Import intermixed, it is bad practice to include these other options after objects are loaded.
NOTE: Not available in pre-1.1 versions.

Object Configuration

ObjectID

ObjectID is used to specify (and thus, internally to Epoch, create) an object. All Object* configuration attributes that follow will target the object specified with ObjectID, until another ObjectID attribute is encountered. ObjectIDs are ASCII, however they may not contain any whitespace.

ObjectDescription

ObjectDescription is used to set the long, descriptive name of objects for Epoch. This is used as the description when booting and shutting down, etc. Values are ASCII and may contain spaces. If not specified, the ObjectID attribute is used as the description.
NOTE: In 1.0 RC1 and earlier, not specifying an ObjectDescription attribute will draw a warning, and change the description of the selected object to "[missing description]".

ObjectReloadCommand

ObjectReloadCommand, if specified, sets the command that will be run for that object if 'epoch reload objectname' is executed. This is useful for services like squid that can have their configuration reloaded without completely restarting the service. Specifying 'SIGNAL num' or e.g.'SIGNAL SIGKILL' sends a signal to the object on reload rather than execute a command.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

ObjectPrestartCommand

ObjectPrestartCommand is executed directly before ObjectStartCommand, but only if it is specified. If specified, it's PID will not be tracked and it's failure will cause a successful execution of ObjectStartCommand to return with a warning.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

ObjectStartCommand

ObjectStartCommand is used to specify the... start... command, for a given object. This is what will be executed when the object is started, such as if it is listed in the default runlevel at bootup, or started manually with the epoch command. It's content is processed by /bin/sh, and it may contain any and all characters, but, like everything in Epoch, cannot occupy more than one line. ObjectStartCommand can be ommitted if the HALTONLY option is set for the object to which it corresponds.

ObjectStopCommand

ObjectStopCommand is the opposite of ObjectStartCommand. It is the command or method used to stop an object. It may contain a command, or it's values may be "PID" or "PIDFILE". You can either specify the PID file with ObjectPIDFile or you may add the location of the file following PIDFILE, such as "PIDFILE /location.pid". Objects stopped with PID or PIDFILE will be sent either SIGTERM (the default) or whatever signal is specified by the ObjectOptions option TERMSIGNAL, upon being stopped. If no stop command is desired, you can omit this or set it's value to "NONE". There is a special case with specifying KILLALL5. You can specify a signal number, followed by the number of seconds to wait before proceeding. Both of these fields are optional. e.g. "ObjectStopCommand=KILLALL5 9 2" is equivalent to killall5 -9;sleep 2, but does not need to call another process because Epoch comes with it's own killall5 implementation.

ObjectStartPriority

ObjectStartPriority is used to specify the order in which objects start during bootup and in runlevel shifts. The number must be a valid integer. A priority of 0 (zero) means that this object will not be launched on bootup or runlevel changes, but can still be started manually via the "epoch" command, and it's ObjectStopCommand atrribute will still be processed on a shutdown or runlevel shift if the object is running, given that the ObjectStopPriority is non-zero. Empty gaps in numbering order are skipped without consequence, to allow for runlevels with some items enabled and others disabled. It is also legal for two objects to have the same priority number, which is often useful for grouping objects, but remember that the order in which objects with the same priority start is not defined.

NOTE: All versions before and including 1.0 Beta 1 do not allow objects to have the same priorities, and this is considered a critical error in some versions. Nevertheless, for the sake of organization, you are encouraged to use objects with the same priorities in versions that support them.

ObjectStopPriority

ObjectStopPriority is the opposite of ObjectStartPriority. It is used to specify the order in which objects are stopped. It can be ommitted if ObjectStopCommand is NONE or not specified.

ObjectPIDFile

ObjectPIDFile is used to specify the location of a PID file to be used to track the PID of the object. Objects with this attribute will wait until their PID file appears before being marked completed, so make sure the specified location is accurate.

If not specified, then PID tracking is done via /proc automatically, but this has downsides and for a select few services, may not be wise due to their habit of changing their process name (argv[0]), which makes Epoch unable to automatically track them beyond the PID it harvested when launching it.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

ObjectWorkingDirectory

ObjectWorkingDirectory is used to specify the current/working directory that the object will change to ('cd') before execution. This attribute is optional.

ObjectUser

ObjectUser specifies the user (as an ASCII name) that the specified object will run as. It only applies to ObjectStartCommand. Everything else is executed as user root (0), including the stop commands. This attribute is optional.

ObjectGroup

ObjectGroup specifies the group (as an ASCII name) that the specified object will run as. It only applies to ObjectStartCommand. Everything else is executed as group root (0), including the stop commands. This attribute is optional.

ObjectStdout

ObjectStdout is used to specify a file to write the output of stdout to. Specifying LOG sets output to Epoch's system.log. The output file need not have writable permissions by any user/group set by ObjectUser and ObjectGroup. This attribute is optional.

ObjectStderr

ObjectStderr is identical to ObjectStdout, except that it affects stderr instead of stdout.

ObjectEnvVar

ObjectEnvVar is analogous to GlobalEnvVar, but only applies the environment variable to the object to which it is applied.
NOTE: Not available in pre-1.1 versions.

ObjectEnabled

ObjectEnabled is used to specify if an object is enabled for ANY runlevels in ANY situations. If "false", the object will be ignored during bootup and will not be started by runlevel changes, but can still be stopped by runlevel changes and shutdowns, provided the PERSISTENT option is not set for the object.
NOTE: The behaviour of 1.0 Alpha 1 and previous is different. The object will be ignored during shutdown as well.

ObjectRunlevels

ObjectRunlevels is used to specify the runlevels for an object. It's values are ASCII, and multiple runlevels may be specified on one line separated by spaces. Runlevels must have at least one object using them to be considered valid. You may not specify multiple ObjectRunlevels attributes for one object, because the config file editor is not smart enough to handle multiple lines at this time. Place all runlevels on the same line.

ObjectOptions

ObjectOptions is used to specify various options about objects and the way they look and behave. Multiple options may be present on one line, separated by whitespace. ----
Back to Epoch Init System homepage