NAME
Ubic::Manual::Overview - General ubic concepts and architecture
VERSION
version 1.38_01
DESCRIPTION
Services and service dir
Ubic service is an object describing how your service works.
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 script is the main tool for manipulating your services.
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
Every service can report its status via status method.
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
Since service descriptions are just a perl code, you get the full power of code reuse, and especially OOP-style code reuse, i.e. inheritance.
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
Service dir can contain subfolders with service definitions inside of these subfolders. It allows you to group your services together and make group operations on them. For example, if you have /etc/ubic/service/my/foo and /etc/ubic/service/my/bar configs, ubic stop -f my will stop both my.foo and my.bar services.
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
Every service is meant to be started by a specific user and group. Service can either provide user and group itself, or default user will be used.
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
Default installation provides some services out of the box. The most important of them is ubic.watchdog.
Watchdog service checks every service status periodically and restarts them if they are broken or down.
AUTHOR
Vyacheslav Matyukhin <mmcleric@yandex-team.ru>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Yandex LLC.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.