NAME

VERSION

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

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

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):

LSB METHODS

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

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

Yury Zavarin <yury.zavarin@gmail.com>

Dmitry Yashin

Christian Walde <walde.christian@googlemail.com>

Ivan Bessarabov <ivan@bessarabov.ru>

Oleg Komarov <komarov@cpan.org>

Andrew Kirkpatrick <ubermonk@gmail.com>

SEE ALSO

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

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

AUTHOR

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.