2 Jump Start

This chapter gives a short overview of dmd. It is enough if you just need the basic features of it. As it is not assumed that readers are familiar with all the involved issues, a very experienced user might be annoyed by the often very detailed descriptions in this introduction. Those users are encouraged to just skip to the reference section.

Note that all the full file names in the following text are based on the assumption that you have installed dmd with an empty prefix. If your dmd installation for example resides in /usr/local instead, add this directory name in front of the absolute file names mentioned below.

When dmd gets started, it reads and evaluates a configuration file. When it is started with superuser priviledges, it tries to use /etc/dmdconf.scm, when started as normal user, it looks for a file called .dmdconf.scm in the user’s home directory. With the option --config (or, for short, -c), you can specify where to look instead. So if you want to start dmd with an alternative file, use one of the following commands:

dmd --config=/etc/dmdconf.scm.old
dmd -c /etc/dmdconf.scm.old

As its name suggests, dmd is just a daemon that (usually) runs in the background, so you will not interact with it directly. After it is started, dmd will listen on a socket special file, usually /var/run/dmd/socket, for further commands. You use the tool deco to send these commands to dmd. Usage of deco is simple and straightforward: To start a service called apache, you use:

deco start apache

When you do this, all its dependencies will get resolved. For example, a webserver is quite likely to depend on working networking, thus it will depend on a service called networking. So if you want to start apache, and networking is not yet running, it will automatically be started as well. The current status of all the services defined in the configuration file can be queried like this:

deco status dmd

Or, to get additional details about each service, run:

deco detailed-status dmd

In this example, this would show the networking and apache services as started. If you just want to know the status of the apache service, run:

deco status apache

You can stop a service and all the services that depend on it will be stopped. Using the example above, if you stop networking, the service apache will be stopped as well—which makes perfect sense, as it cannot work without the network being up. To actually stop a service, you use the following, probably not very surprising, command:

deco stop networking

There are two more actions you can perform on every service: The actions enable and disable are used to prevent and allow starting of the particular service. If a service is intended to be restarted whenever it terminates (how this can be done will not be covered in this introduction), but it is respawning too often in a short period of time (by default 5 times in 5 seconds), it will automatically be disabled. After you have fixed the problem that caused it from being respawned too fast, you can start it again with the commands:

deco enable foo
deco start foo

But there is far more you can do than just that. Services can not only simply depend on other services, they can also depend on virtual services. A virtual service is a service that is provided by one or more service additionally. For instance, a service called exim might provide the virtual service mailer-daemon. That could as well be provided by a service called smail, as both are mailer-daemons. If a service needs any mailer-daemon, no matter which one, it can just depend on mailer-daemon, and one of those who provide it gets started (if none is running yet) when resolving dependencies. The nice thing is that, if trying to start one of them fails, dmd will go on and try to start the next one, so you can also use virtual services for specifying fallbacks.

Additionally to all that, you can perform service-specific actions. Coming back to our original example, apache is able to reload its modules, therefore the action reload-modules might be available:

deco reload-modules apache

The service-specific actions can only be used when the service is started, i.e. the only thing you can do to a stopped service is starting it. An exception exists, see below. (If you may at some point find this too restrictive because you want to use variants of the same service which are started in different ways, consider using different services for those variants instead, which all provide the same virtual service and thus conflict with each other, if this is desired. That’s one of the reasons why virtual services exist, after all.)

There are two actions which are special, because even if services can implement them on their own, a default implementation is provided by dmd (another reason why they are special is that the default implementations can be called even when the service is not running; this inconsistency is just to make it more intuitive to get information about the status of a service, see below).

These actions are restart and status. The default implementation of restart calls stop and start on the affected service in order, the status action displays some general information about the service, like what it provides, what it depends on and with which other services it conflicts (because they provide a virtual service that is also provided by that particular service).

Another special action is list-actions, which displays a list of the additional actions a service provides; obviously, it can also be called when the service is not running. Services cannot provide their own implementation of list-actions.

A special service is dmd, which is used for controlling dmd itself. It implements various actions. For example, the status action displays which services are started and which ones are stopped, whereas detailed-status has the effect of applying the default implementation of status to all services one after another. The load action is unusual insofar as it shows a feature that is actually available to all services, but which we have not seen yet: It takes an additional argument. You can use load to load arbitrary code into dmd at runtime, like this:

deco load dmd ~/additional-services.scm

This is enough now about the deco and dmd programs, we will now take a look at how to configure dmd. In the configuration file, we need mainly the definition of services. We can also do various other things there, like starting a few services already.

FIXME: Finish. For now, look at the examples/ subdirectory.

...

Ok, to summarize:

• dmd is a daemon, deco the program that controls it.
• You can start, stop, restart, enable and disable every service, as well as display its status.
• You can perform additional service-specific actions, which you can also list.
• Actions can have arguments.
• You can display the status of a service, even if the service does not provide a specific implementation for this action. The same is true for restarting.
• The dmd service is used to control dmd itself.