/ 
Ubic-1.44_03
River stage two • 9 direct dependents • 15 total dependents
/ Ubic

NAME

Ubic - polymorphic service manager

VERSION

version 1.44_03

SYNOPSIS

Configure ubic:
$ ubic-admin setup

Write the service config:
$ cat >/etc/ubic/service/foo.ini
[options]
bin = /usr/bin/foo.pl

Start your service:
$ ubic start foo

Enjoy your daemonized, monitored service.

DESCRIPTION

This module is a perl frontend to ubic services.

It is a singleton OOP class. All of its methods should be invoked as class methods:

Ubic->start('foo');
Ubic->stop('foo');
my $status = Ubic->status('foo');

INTRODUCTION

Ubic is a polymorphic service manager.

Further directions:

if you are looking for a general introduction to Ubic, see Ubic::Manual::Intro;

if you want to use ubic from the command line, see ubic;

if you want to manage ubic services from the perl scripts, read this POD;

if you want to write your own service, see Ubic::Service and other Ubic::Service::* modules.

CONSTRUCTOR

Ubic->new({ ... })

All methods in this package can be invoked as class methods, but sometimes you may need to override some status dirs. In this case you should construct your own Ubic instance.

Note that you can't create several instances in one process and have them work independently. So, this constructor is actually just a weird way to override service_dir and data_dir.

Constructor options (all of them are optional):

service_dir

Name of dir with service descriptions (which will be used to construct root Ubic::Multiservice::Dir object).

data_dir

Dir into which ubic stores all of its data (locks, status files, tmp files).

LSB METHODS

See LSB documentation for init-script method specifications.

Following methods are trying to conform, except that all dashes in method names are replaced with underscores.

These methods return the result objects, i.e., instances of the Ubic::Result::Class class.

start($name)

Start the service.

stop($name)

Stop the service.

restart($name)

Restart the service; start it if it's not running.

try_restart($name)

Restart the service if it is enabled.

reload($name)

Reload the service.

This method will do reloading if the service implements reload(); it will throw an exception otherwise.

force_reload($name)

Reload the service if reloading is implemented, otherwise restart it.

Does nothing if service is disabled.

status($name)

Get the service status.

OTHER METHODS

enable($name)

Enable the service.

Enabled service means that service should be running.

Watchdog will periodically check its status, attempt to restart it and mark it as broken if it won't succeed.

is_enabled($name)

Check whether the service is enabled.

Returns true or false.

disable($name)

Disable the service.

Disabled service means that the service is ignored by ubic.

Its state will no longer be checked by the watchdog, and ubic status will report that the service is down.

cached_status($name)

Get cached status of the service.

Unlike other methods, it can be invoked by any user.

do_custom_command($name, $command)

Execute the custom command $command for the given service.

service($name)

Get service object by name.

has_service($name)

Check whether the service named $name exists.

services()

Get the list of all services.

service_names()

Get the list of all service names.

root_service()

Get the root multiservice object.

Root service doesn't have a name and returns all top-level services with services() method. You can use it to traverse the whole service tree.

compl_services($line)

Get the list of autocompletion variants for a given service prefix.

set_cached_status($name, $status)

Write the new status into the service's status file.

get_data_dir()

Get the data dir.

set_data_dir($dir)

Set the data dir, creating it if necessary.

Data dir is a directory with service statuses and locks. (See Ubic::Settings for more details on how it's chosen).

This setting will be propagated into subprocesses using environment, so the following code works:

Ubic->set_data_dir('tfiles/ubic');
Ubic->set_service_dir('etc/ubic/service');
system('ubic start some_service');
system('ubic stop some_service');
set_ubic_dir($dir)

Deprecated. This method got renamed to set_data_dir().

set_default_user($user)

Set default user for all services.

This is a simple proxy for Ubic::Settings->default_user($user).

get_service_dir()

Get the ubic services dir.

set_service_dir($dir)

Set the ubic services dir.

INTERNAL METHODS

You shouldn't call these from a code which doesn't belong to core Ubic distribution.

These methods can be changed or removed without further notice.

status_file($name)

Get the status file name by a service's name.

status_obj($name)

Get the status persistent object by a service's name.

It's a bad idea to call this from any other class than Ubic, but if you'll ever want to do this, at least don't forget to create Ubic::AccessGuard first.

status_obj_ro($name)

Get the readonly, nonlocked status persistent object (see Ubic::Persistent) by a service's name.

access_guard($name)

Get an access guard (Ubic::AccessGuard object) for the given service.

lock($name)

Acquire lock object for given service.

You can lock one object twice from the same process, but not from different processes.

do_sub($code)

Run any code and wrap any result or exception into a result object.

do_cmd($name, $cmd)

Run $cmd method from the service named $name and wrap any result or exception in a result object.

forked_call($callback)

Run a $callback in a subprocess and return its return value.

Interaction happens through a temporary file in $ubic->{tmp_dir} dir.

CONTRIBUTORS

Andrei Mishchenko <druxa@yandex-team.ru>

Yury Zavarin <yury.zavarin@gmail.com>

Dmitry Yashin

Christian Walde <walde.christian@googlemail.com>

Ivan Bessarabov <ivan@bessarabov.ru>

SEE ALSO

Most Ubic-related links are collected on github wiki: http://github.com/berekuk/Ubic/wiki.

Daemon::Control and Proc::Launcher provide the start/stop/status style mechanisms for init scripts and apachectl-style commands.

Server::Control is an apachectl-style, heavyweight subclassable module for handling network daemons.

ControlFreak - process supervisor, similar to Ubic in its command-line interface.

There are also App::Daemon, App::Control and Supervisor.

SUPPORT

Our IRC channel is irc://irc.perl.org#ubic.

There's also a mailing list at ubic-perl@googlegroups.com. Send an empty message to ubic-perl+subscribe@googlegroups.com to subscribe.

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.