Services and service dir

Service object must conform to the API of the Ubic::Service class, so it must implement "start", "stop" and "status" methods. It can also provide other methods: which user should be used to run the service, how often the service should be checked by the watchdog, etc.

Service declarations are stored in ubic service dir. Service declaration is a single file with perl code which returns service object when executed with "do". If you use host-level installation, service dir is /etc/ubic/service. If you prefer installation to home dir, service dir is ~/ubic/service.

Service file name can contain digits, letters underscores and dashes. Dot is not a valid symbol and all files with dots in their names will be ignored.

'ubic' script

"ubic status" command, for example, will show the list of all services declared in service dir, along with their statuses. "ubic start" and "ubic stop" can be used to start and stop all or some services. Refer to ubic POD for more details.

Service status

In the plane of perl API, statuses are instances of Ubic::Result class. Refer to its POD for gory details on various possible status values.

Beside the real status, which can be calculated by calling "status" method, there is also the cached status, stored on the disk in the special data dir. This status is used in two ways. First, users without appropriate rights to run actual status check, can invoke "ubic status" command and see cached statuses. Second, watchdog process compares cached status with current status to identify broken services and bring them back to life.

Common service classes

The most important property of well-behaved service is that it would prevent you from starting it twice, won't fail if you try to stop it twice, and will report correct statuses in all conditions. "Ubic::Service::Skeleton" helps you to do these things by asking for current service status before start and stop operations. It also solves the common task of re-asking service status in a loop with sleeps on start.

"Ubic::Service::Common" class is very similar to "Ubic::Service::Skeleton", but it allows you to pass start/stop/status code via callbacks instead of inheritance.

Finally, there is "Ubic::Service::SimpleDaemon", which can turn any script or binary into service. It uses "Ubic::Daemon" module for all daemonization stuff.

There are also some other modules on CPAN for more specific tasks: Ubic::Service::Plack, Ubic::Service::Memcached.

Service tree

What's even more interesting is that subfolders with separate files in them is not the only way to populate service tree. Read Ubic::Manual::Multiservices to learn more!

Permissions and security

Default user is "root" on system-wide installations, and the home folder owner on home dir installations. You can change it in global "ubic.cfg" file.

All service operations are performed using its user and group: start/stop operations, status checks, status file updates, watchdog checks. Ubic tries to change user to service user as soon as possible (but it still happens after service definition's compilation, of course). It means that service not only always started from correct user, even if you called "ubic start foo" being root, for example, but also that service user is always has enough grants to operate service too.

This feature requires 1777 grants to ubic data dir (readable and writable for everyone, but with sticky bit enabled). It should be secure, but if it worries you, you can try to change it to 1577 (writable for specific group), and add all service users to this group.

Note also that you can't change user of existing service and expect your service to work. Refer to "Permission denied" question in Ubic::Manual::FAQ for more on this.

Watchdog

Watchdog service checks every service status periodically and restarts them if they are broken or down.