Epoch Init System - Configuration Documentation

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 subsentient@universe2.us. A sample configuration file is available here. Place it at /etc/epoch/epoch.conf.

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.

StartingStatusFormat

Used to specify an alternate first-half of the status report seen on service completion. e.g. where it could be "Starting MyService ... Done" during bootup or shutdown etc. To specify the title of the object in formatting, use "!TITLE!", e.g. " * [!TITLE!] " will produce " * [Starting MyService] ". Optionally, you may specify a file with "FILE /location.txt" from which Epoch will load the formatting.
Color codes and such characters are permitted, but must be entered in raw form. If you wish to use color codes, perhaps it's best to use "FILE".
NOTE: Not available in pre-1.2.0 versions.

FinishedStatusFormat

Analogous to StartingStatusFormat, but for the segment of the status report that reports success or failure, etc. In addition to !TITLE!, !STATUS! is now available for formatting. If a file is not specified with "FILE /", then a newline is appended to the end of this formatting.
NOTE: Not available in pre-1.2.0 versions.

StatusNames

Used to specify the names and formatting of the FAILURE, Done, and WARNING conditions for status reports. The formatting if NOT specified in a file is StatusNames=FailName,OkName,WarningName. If from a file with "FILE /location.txt", the formatting is: "FailName OkName WarningName" Trailing whitespace is removed during processing (but not preceding whitespace). Color codes are valid but there is intentionally no way to add newlines to these status names.
NOTE: Not available in pre-1.2.0 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, and objects are started in forward order, e.g. 1 is started before 2. 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 its 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 in relation to each other is not defined.

ObjectStopPriority

ObjectStopPriority is the opposite of ObjectStartPriority. It is used to specify the order in which objects are stopped. Again, it works in forward order, where 1 will be stopped before 2. It can be ommitted if ObjectStopCommand is NONE or not specified, or if you don't desire to have the stop command run other than explicit calls to 'epoch stop'.

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.

RAWDESCRIPTION: Does not append "Starting" or "Stopping" to beginning of the description when booting or shutting down. Useful for creating a custom description, such as "Configuring something".

FORK: Items with this option are launched in such a way that Epoch will not wait for them to complete before moving to the next object. It is similar to a /bin/sh trick 'cmd&', except that because objects with FORK set almost always return success.
NOTE: This attribute requires Epoch to be built WITHOUT passing --nommu. It will not function on systems that have no MMU and attempting to use it on such systems will draw a warning. Objects with FORK set will also wait for a PID that matches the command to appear before completing. See FORKN for a fork option that does not do this, which might be desired in the case of a one-time-quick-job type object.
NOTE: If you are specifying this to launch a program that usually never exits on it's own yet does not daemonize, DO NOT specify the SERVICE option as well! This causes PID tracking failures and can lead to services dying and false-autorestarts. A common not-a-bug scenario arises from this and gettys.

FORKN: Same as FORK, but doesn't wait for the appropriate PID to appear before completion. Useful for forking commands that will complete very quickly and exit.
NOTE: This option is not present on versions below 1.1.

PIVOT: Objects with this option are treated specially. They may not have ObjectStopCommand attributes, and most other options will prove useless or will draw warnings. These objects are used to dictate parameters to switch to a new root filesystem, a kind of permanent chroot. This is required for initrds, initramfs, etc. ObjectStartCommand must be present. ObjectStartCommand's syntax for a pivot_root is as such:
ObjectStartCommand=/mnt/disk1 /mnt/disk1/mnt/old
The first half is the directory the new root filesystem is currently mounted on, and the second half is where the old root filesystem will be mounted. You can unmount the old prior to starting a new init, since a separate object with EXEC set is required to fully replace Epoch with a new binary. The advantage of doing the pivot_root and exec() separately is the ability to mount/unmount/etc other things as the new root filesystem prior to executing the new init. EXEC and PIVOT may not be present on the same object, since that's meaningless.

EXEC: Objects with this option are treated specially. They may not have stop commands, and many options will prove useless or will draw warnings when applied to them. EXEC is used to replace the current init, in this case Epoch, with a new binary that retains Epoch's PID 1. Usually used in conjunction with a separate object with PIVOT set, because both are usually needed when using an initramfs/initrd. Setting both PIVOT and EXEC is illegal because it makes no sense. You need separate objects for that. Their ObjectStartCommands are not processed by /bin/sh, so calling them with sh-specific commands usually results in you being dumped to an emergency shell.

PERSISTENT: Ensures that an object cannot be stopped during runlevel changes, and only during a system shutdown or manually via the "epoch" command.

SERVICE: Used to tell Epoch that this object will likely daemonize. It is used to assist the tracking of the PID for the object, though this option is usually not necessary. It is still, however, recommended that you use it for daemonizing services to prevent off-cases.

AUTORESTART: Objects with this attribute are restarted whenever their PID is no longer running. If the object is stopped somehow, the effect of automatic restart ends until the object is started by the user again.

RUNONCE: After the object's initial start (or in the case that HALTONLY is specified, stop), it is immediately disabled so that it will not run again on the next boot. This is useful for post-install tasks for Linux distributions such as generating ssh keys on the first boot. The object can still be manually started and re-enabled via 'epoch enable'.
NOTE: Versions prior to 1.1 do not have this option.

STOPTIMEOUT: Used to specify time in seconds to wait for an object's PID to exit. Syntax is STOPTIMEOUT=20 etc.

NOSTOPWAIT: Prevents Epoch from waiting for the object's process to exit when running the stop command or terminating by PID etc.

HALTONLY: Objects with this attribute have no start command, no start priority, and require no runlevels to be set. They are not affected by runlevel changes whatsoever, and are only executed when the system is shutting down. ObjectStartCommand should not be specified for objects with this option.

TERMSIGNAL: If you set TERMSIGNAL=signal, that signal will be sent to PID and PIDFILE stop-moded objects when they are stopped. It can either be a number, or one of SIGTERM, SIGKILL, SIGHUP, SIGINT, SIGABRT, SIGQUIT, SIGUSR1, or SIGUSR2.
NOTE: This attribute is not available in 1.0 Beta 1 and earlier.

FORCESHELL: If this option is set, Epoch will insist that /bin/sh (or whatever shell Epoch was compiled to use) be used to process all commands for this object. This is not necessary usually, since Epoch detects symbols that would usually require a shell, but to use inbuilt shell commands such as 'echo', this is indeed necessary.
NOTE: This option requires Epoch be built with shell support, otherwise it has no effect and will draw warnings.
NOTE: This option is not available in 1.0 Beta 1 and earlier.

STARTFAILCRITICAL: Denotes that it is a critical error in the boot process for the object to fail. In the event that the object fails to start, the system is dropped to an emergency shell and Epoch is shut down. Failures of objects with this option are only deemed critical during boot. Failure during manual starts and runlevel changes are not considered critical.
NOTE: Versions below 1.1 do not have this option.

STOPFAILCRITICAL: Same as STARTFAILCRITICAL, but denotes that failure during shutdown is critical rather than failure during bootup.
NOTE: Versions below 1.1 do not have this option.

NOTRACK: Forces Epoch not to track the PID of the object during it's launch. The object's PID will still likely be tracked after the object is started.
NOTE: Versions below 1.1 do not have this option.

MAPEXITSTATUS: Used to specify non-default results for exit codes. For example, "ObjectOptions=MAPEXITSTATUS=2,WARNING" will denote that if the object's start command returns exit code 2, that this is to result in a warning rather than a failure. Valid values other than WARNING are FAILURE and SUCCESS. Specified exit code must be within the range for UNIX/Linux exit codes.
NOTE: This option is not present in versions below 1.1.

----
Back to Epoch Init System homepage