Developers Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


Tutorials Managing Daemons

This tutorial is a guide for getting started with apps that are built around running daemons. There are standard widgets and APIs included in ClearOS that will simplify your life and provide a consistent user experience.

Daemon Library

Daemon API

For your daemon-based app, the first place you want to start is the daemon class. This base class provides a handy API – you can do things like restart a daemon, get the status of the daemon, and do other basic daemon tasks. Here's a bird's eye view of the API:

  • get_boot_state()
  • get_running_state()
  • get_process_id($skip_pidof = FALSE)
  • get_process_name()
  • get_status()
  • get_title()
  • reset($background = FALSE)
  • restart($background = TRUE)
  • set_boot_state($state)
  • set_running_state($state)

The API is fairly self-explanatory, but you can find the full documentation here.

Configlet - /var/clearos/base/daemon

Before you can start using the base Daemon API, a simple configlet definition needs to be dropped into the /var/clearos/base/daemon directory on your ClearOS system. This configlet filename must match the init script name used in /etc/init.d followed by the php suffix. The contents of the configlet provides all the information needed to get the Daemon class working for a specific Linux daemon.

Let's step through the OpenVPN app as an example. For OpenVPN, the configlet filename is /var/clearos/base/daemon/openvpn.php and the pertinent configuration information is shown below:

$configlet = array(
        'title' => lang('openvpn_app_name'),
        'package' => 'openvpn',
        'process_name' => 'openvpn',
        'reloadable' => FALSE,
        'url' => '/app/openvpn'
);

The description of each array item is given in the following table:

ItemDescription
titleThe app name title
packageThe RPM package name that contains the daemon
process_nameThe process name (what you see in the “ps” output)
reloadableA flag indicating whether or not the daemon supports reloading (instead of a full restart)
urlThe app URL (if applicable)
pid_fileProcess ID file (if available)

You may have noticed that the pid_file parameter is not specified in the OpenVPN example. OpenVPN does not handle its PID file in a normal way, so it is omitted. If your daemon uses a consistent PID file (typically /var/run/daemon_name.pid), then please specify it! With the PID file information, it's possible for the Daemon class to detect a dead (crashed) daemon.

Sample Script

With your configlet file in place, you can now use the Daemon class. Here's an example script using OpenVPN:

#!/usr/clearos/sandbox/usr/bin/php
<?php
 
///////////////////////////////////////////////////////////////////////////////
// B O O T S T R A P
///////////////////////////////////////////////////////////////////////////////
 
$bootstrap = getenv('CLEAROS_BOOTSTRAP') ? getenv('CLEAROS_BOOTSTRAP') : '/usr/clearos/framework/shared';
require_once $bootstrap . '/bootstrap.php';
 
///////////////////////////////////////////////////////////////////////////////
// D E P E N D E N C I E S
///////////////////////////////////////////////////////////////////////////////
 
use \clearos\apps\base\Daemon as Daemon;
 
clearos_load_library('base/Daemon');
 
///////////////////////////////////////////////////////////////////////////////
// M A I N
///////////////////////////////////////////////////////////////////////////////
 
$daemon = new Daemon('openvpn');
echo "running status: " . $daemon->get_status() . "\n";
echo "process ID: " . $daemon->get_process_id() . "\n";

Once you have success with your configlet and a test script, you can move on to the next step: extending the Daemon class.

Extending the Daemon Class

The script shown in the previous section is not the usual way to access the Daemon API. Instead, a new class for your app can extend the Daemon class. Here's the OpenVPN skeleton code:

class OpenVPN extends Daemon
{
    public function __construct()
    {
        clearos_profile(__METHOD__, __LINE__);
 
        parent::__construct('openvpn');
    }
 
    // Other API calls here
}

The parameter passed to the parent is the basename of the configlet file added in /var/clearos/base/daemon. Go ahead and take a look at other daemon-based apps for examples: pptpd, web_proxy, radius, and many others.

By extending the base Daemon class and specifying a few lines in a configlet file, a handy set of API calls are ready to use!

Webconfig Widget

ClearOS Daemon WidgetNow that you are familiar with the underlying Daemon class, it's time to move on the web-based interface. As you have probably already noticed, a webconfig widget exists for starting/stopping a daemon (see adjacent screenshot). The advantages of using this widget:

  • Consistent look and feel
  • Quick and easy to implement
  • Mobile friendly

Just as you can extend the Daemon library, you can also extend the Daemon controller to create the webconfig widget. In the OpenVPN controllers directory, you will see a file called server.php which contains:

<?php
 
///////////////////////////////////////////////////////////////////////////////
// B O O T S T R A P
///////////////////////////////////////////////////////////////////////////////
 
$bootstrap = getenv('CLEAROS_BOOTSTRAP') ? getenv('CLEAROS_BOOTSTRAP') : '/usr/clearos/framework/shared';
require_once $bootstrap . '/bootstrap.php';
 
///////////////////////////////////////////////////////////////////////////////
// D E P E N D E N C I E S
///////////////////////////////////////////////////////////////////////////////
 
require clearos_app_base('base') . '/controllers/daemon.php';
 
///////////////////////////////////////////////////////////////////////////////
// C L A S S
///////////////////////////////////////////////////////////////////////////////
 
class Server extends Daemon
{
    function __construct()
    {
        parent::__construct('openvpn', 'openvpn');
    }
}

The constructor parameters are:

  • Daemon name: the basename of the file dropped into /var/clearos/base/daemons
  • App name: the basename of the app

That covers the server.php file. In order to see the daemon widget, you need to add the server controller to the list of controllers in your default controller. For OpenVPN, the default controller (openvpn.php):

… snip … $controllers = array('openvpn/server', 'openvpn/settings');

$this→page→view_controllers($controllers, lang('openvpn_app_name'));

content/en_us/dev_framework_tutorials_managing_daemons.txt · Last modified: 2014/12/23 15:29 by dloper

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Adev_framework_tutorials_managing_daemons&1710815277