Ubic::Manual::Overview - General ubic concepts and architecture
version 1.51
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.
start
stop
status
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.
do
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 is the main tool for manipulating your services.
ubic
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.
ubic status
ubic start
ubic stop
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.
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::Skeleton
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.
Ubic::Service::Common
Finally, there is Ubic::Service::SimpleDaemon, which can turn any script or binary into service. It uses Ubic::Daemon module for all daemonization stuff.
Ubic::Service::SimpleDaemon
Ubic::Daemon
There are also some other modules on CPAN for more specific tasks: Ubic::Service::Plack, Ubic::Service::Memcached.
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.
/etc/ubic/service/my/foo
/etc/ubic/service/my/bar
ubic stop -f my
my.foo
my.bar
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!
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.
root
ubic.cfg
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.
ubic start foo
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.
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.
Vyacheslav Matyukhin <mmcleric@yandex-team.ru>
This software is copyright (c) 2013 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.
To install Ubic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ubic
CPAN shell
perl -MCPAN -e shell install Ubic
For more information on module installation, please visit the detailed CPAN module installation guide.