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

FreeBSD Manual Pages

  
 
  

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

NAME
       Ubic::Daemon - daemon management	utilities

VERSION
       version 1.58

SYNOPSIS
	   use Ubic::Daemon qw(start_daemon stop_daemon	check_daemon);

	   start_daemon({bin =>	'/bin/sleep', pidfile => "/var/lib/something/pid"});
	   stop_daemon("/var/lib/something/pid");

	   $daemon_status = check_daemon("/var/lib/something/pid");

DESCRIPTION
       This module provides functions which let	you daemonize any binary or
       perl coderef.

       Main source of knowledge	if daemon is still running is pidfile, which
       is locked all the time after daemon was created.

       Note that pidfile format	is unreliable and can change in	future
       releases	(it's actually even not	a file,	it's a dir with	several	files
       inside it), so if you need to get daemon's pid, don't try to read
       pidfile directly, use "check_daemon()" function.

       stop_daemon($pidfile)
       stop_daemon($pidfile, $options)
	   Stop	daemon which was started with $pidfile.

	   It sends SIGTERM to process with pid	specified in $pidfile until it
	   will	stop to	exist (according to "check_daemon()" method).

	   If it fails to stop process after several seconds, exception	will
	   be raised (this should never	happen,	assuming you have enough
	   grants).

	   Options:

	   timeout
	       Number of seconds to wait before	raising	exception that daemon
	       can't be	stopped.

	   Return value: "not running" if daemon is already not	running;
	   "stopped" if	daemon is stopped by SIGTERM.

       start_daemon($params)
	   Start daemon.

	   Throws exception if anything	fails.

	   Successful completion doesn't mean much, though, since daemon can
	   fail	any moment later, and we have no idea when its initialization
	   stage finishes.

	   Parameters:

	   bin Binary which will be daemonized.

	       Can be string or	arrayref with arguments. Arrayref-style	values
	       are recommended in complex cases, because otherwise "exec()"
	       can invoke sh shell which will immediately exit on sigterm.

	   function
	       Function	which will be daemonized. One and only one of function
	       and bin must be specified.

	       Function	daemonization is a dangerous feature and will probably
	       be deprecated and removed in future.

	   name
	       Name of guardian	process. Guardian will be named	"ubic-guardian
	       $name".

	       If not specified, bin's value will be used, or "anonymous" when
	       daemonizing perl	code.

	   pidfile
	       Pidfile is a dir	in local filesystem which will be used as a
	       storage of daemon's info.

	       It will be created if necessary,	assuming that its parent dir
	       exists.

	   stdout
	       Write all daemon's output to given file.	If not specified, all
	       output will be redirected to "/dev/null".

	   stderr
	       Write all daemon's error	output to given	file. If not
	       specified, all stderr will be redirected	to "/dev/null".

	   ubic_log
	       Optional	filename of ubic log. Log will contain some technical
	       information about running daemon.

	       If not specified, this logging facility will be disabled.

	   cwd Change working directory	before starting	a daemon. Optional.

	   env Modify environment before starting a daemon. Optional. Must be
	       a plain hashref if specified.

	   proxy_logs
	       Boolean flag.

	       If enabled, "ubic-guardian" will	replace	daemon's stdout	and
	       stderr filehandles with pipes, proxy all	data to	the log	files,
	       and reopen them on SIGHUP.

	       There're	two reasons why	this is	not the	default:

	       1) It's a bit slower than allowing the daemon to	write its logs
	       itself;

	       2) The code is new and more complex than	the simple "spawn the
	       daemon and wait for it to finish".

	       On the other hand, using	this feature allows you	to reopen all
	       logs without restarting the service.

	   credentials
	       Set given credentials before execing into a daemon. Optional,
	       must be an "Ubic::Credentials" object.

	   start_hook
	       Optional	callback that will be executed before execing into a
	       daemon.

	       This option is a	generalization of cwd and env options. One
	       useful application of it	is setting ulimits: they won't affect
	       your main process, since	this hook will be executed in the
	       context of double-forked	process.

	       Note that hook is called	*before* the credentials are set.
	       Raising the ulimits won't work otherwise.

	   term_timeout
	       Number of seconds to wait between sending SIGTERM and SIGKILL
	       to the daemon on	stopping.

	       Zero value means	that guardian will send	SIGKILL	to the daemon
	       immediately.

	       Default is 10 seconds.

       check_daemon($pidfile)
	   Check whether daemon	is running.

	   Returns instance of Ubic::Daemon::Status class if daemon is alive,
	   and false otherwise.

BUGS AND CAVEATS
       Probably. But it	definitely is ready for	production usage.

       This module is not compatible with Windows by now. It can be fixed by
       implementing correct "Ubic::Daemon::OS::Windows"	module.

       If you wonder why there are "ubic-guardian" processes in	your "ps"
       output, see Ubic::Manual::FAQ, answer is	there.

SEE ALSO
       Ubic::Service::SimpleDaemon - simplest ubic service which uses
       Ubic::Daemon

       There are also a	plenty of other	daemonizers on CPAN:

       MooseX::Daemonize, Proc::Daemon,	Daemon::Generic,
       Net::Server::Daemonize.

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.1			  2015-01-27		       Ubic::Daemon(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | BUGS AND CAVEATS | 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::Daemon&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help