Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Ubic::Service(3)      User Contributed Perl Documentation     Ubic::Service(3)

NAME
       Ubic::Service - interface and the base class for	any ubic service

VERSION
       version 1.58

SYNOPSIS
	   print "Service: ", $service->name;
	   $service->start;
	   $service->stop;
	   $service->restart;
	   $status = $service->status;

DESCRIPTION
       "Ubic::Service" is the abstract base class for all ubic service
       classes.

       It provides the common API for implementing start/stop/status
       operations, custom commands and tuning some metadata properties
       ("user()", "group()", "check_period()").

METHODS
   ACTION METHODS
       All action methods should return	Ubic::Result::Class objects. If	action
       method returns a	plain string, Ubic will	wrap it	into result object for
       you.

       start()
	   Start the service. Should throw an exception	on failure and a
	   result object or a string with operation result otherwise.

	   Starting an already running service should do nothing and return
	   "already running".

       stop()
	   Stop	the service. Should throw an exception on failure and a	result
	   object or a string with operation result otherwise.

	   Stopping an already stopped service should do nothing and return
	   "not	running".

	   Successful stop of a	service	must disable this service.

       status()
	   Check the status of the service.

	   It should check that	service	is running correctly and return
	   "running" if	it is so.

       reload()
	   Reload the service if possible.

	   Throw an exception if reloading is not implemented (default
	   implementation already does so).

   METADATA METHODS
       All metadata methods are	read-only. All of them provide the sane
       defaults.

       port()
	   Get the port	number if a service listens for	a TCP port.

	   Default is "undef".

       user()
	   Get the user	from which the service can be controlled and will be
	   running.

	   Defaults to default_user from Ubic::Settings	(i.e., "root" for a
	   system-wide installation, or	to the installation owner for a	local
	   installation).

       group()
	   Get the list	of groups from which the service can be	controlled and
	   will	be running.

	   First group from the	list will be used as real and effective	group
	   id, and other groups	will be	set as supplementary groups.

	   Default is an empty list, which will	later be interpreted as
	   default group of the	user returned by "user()" method.

       check_period()
	   Period of checking a	service	by watchdog in seconds.

	   Default is 60 seconds and it	is unused by the ubic.watchdog
	   currently, so don't bother to override it by	now :)

       check_timeout()
	   Timeout after which the watchdog will give up on checking the
	   service and will kill itself.

	   This	parameter exists as a precaution against incorrectly
	   implemented "status()" or "start()" methods.	 If a "status()"
	   method hangs, without this timeout, watchdog	would stay in memory
	   forever and never get a chance to restart a service.

	   This	parameter is not a timeout for querying	your service by	HTTP
	   or whatever your status check is. Service-specific timeouts should
	   be configured by other means.

	   Default value is 60 seconds.	It should not be changed unless	you
	   have	a very good reason to do so (i.e., your	service	is so horribly
	   slow	that it	can't start in 1 minute).

   CUSTOM COMMAND METHODS
       Services	can define custom commands which don't fit into	the usual
       "start/stop/restart/status" set.

       custom_commands()
	   Should return the list of service's custom commands,	if there are
	   any.

       do_custom_command($command)
	   Should execute specified command, if	it is supported. Throw an
	   exception otherwise.

   NAME	METHODS
       These methods should not	be overridden by specific service classes.
       They are	usually	used by	the code which loads service (i.e. some	kind
       of Ubic::Multiservice) to associate service with	its name.

       These methods are just the simple interdependent	r/w accessors.

       name()
       name($new_name)
	   Get or set a	name of	the service.

	   Each	service	with the same parent should have an unique name.

	   In case of subservices, this	method should return the most lower-
	   level name.

	   Service implementation classes shouldn't override this or other
	   *_name methods; it's	usually	a service's loader job to set them
	   correctly.

       full_name()
	   Get a fully qualified name of the service.

	   Each	service	must have a unique full_name.

	   Full	name is	a concatenation	of service's short "name" and
	   service's <parent_name>.

       parent_name()
       parent_name($new_parent_name)
	   Get or set a	name of	the service's parent.

	   Service's loader (i.e. some kind of Ubic::Multiservice) is
	   responsible for calling this	method immediately after a service is
	   constructed,	like this: "$service->parent_name($self->full_name)"
	   (check out Ubic::Multiservice sources for more).

       auto_start()
	   A boolean value that	determines the state of	a service if it	has
	   never been explicitly enabled or disabled yet. Service is
	   considered initially	enabled	when auto_start	is true.

	   Default is false, so	initial	service	status is off, and you have to
	   run "ubic start service_name" to start it.

FUTURE DIRECTIONS
       Current API for custom commands is inconvenient and doesn't support
       parameterized commands. It needs	some refactoring.

       Requiring every service to inherit from this class can be seen as
       undesirable by some programmers,	especially by those who	prefer to use
       Moose and roles.	 If you	know how to make this API more role-friendly
       without too much	of converting pains, please contact us at
       ubic-perl@googlegroups.com or at	irc://irc.perl.org#ubic.

SEE ALSO
       Ubic::Service::Skeleton - implement simple start/stop/status methods,
       and ubic	will care about	everything else.

       Ubic::Service::Common - just like Skeleton, but all code	can be passed
       to constructor as sub references.

       Ubic::Service::SimpleDaemon - give it any binary	and it will make a
       service from it.

AUTHOR
       Vyacheslav Matyukhin <mmcleric@yandex-team.ru>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2015 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.

perl v5.32.0			  2015-01-27		      Ubic::Service(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | FUTURE DIRECTIONS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Ubic::Service&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help