Struct inapi::Service

pub struct Service { /* fields omitted */ }

Primitive for controlling service daemons.

Basic Usage

Initialise a new Host:

let mut host = Host::connect("hosts/myhost.json").unwrap();

Create a new Service to manage a daemon (for example, Nginx):

let service = Service::new_service(ServiceRunnable::Service("nginx"), None);

If your daemon uses a script instead of an init system, just change the ServiceRunnable type to Command:

let service = Service::new_service(ServiceRunnable::Command("/usr/bin/apachectl"), None);

Now you can run an action against the Service. This will optionally return a CommandResult if the action was run, or None if the service was already in the desired state.

let result = service.action(&mut host, "start").unwrap();
if let Some(r) = result {
    assert_eq!(r.exit_code, 0);
}

Runnables

Runnables are the executable items that a Service runs.

ServiceRunnable::Service represents a daemon managed by the init system.

For example, on a Linux system using Init, ServiceRunnable::Service("nginx") is executed as:

service nginx <action>

If your daemon does not have an init script, use ServiceRunnable::Command to reference an executable directly.

For example, ServiceRunnable::Command("/usr/bin/nginx") will simply run the executable path /usr/bin/nginx.

Mapping Actions to Runnables

The other way of initialising a Service is with the new_map() function. This allows you to map individual actions to separate ServiceRunnables.

 let mut map = HashMap::new();
 map.insert("start", ServiceRunnable::Command("/usr/local/bin/svc_start"));
 map.insert("stop", ServiceRunnable::Command("/usr/local/bin/svc_stop"));
 map.insert("restart", ServiceRunnable::Command("/usr/local/bin/svc_stop && /usr/local/bin/svc_start"));
 let service = Service::new_map(map, None);

You can also set a default ServiceRunnable. For example, you could map the "status" action to a ServiceRunnable::Command while defaulting to a ServiceRunnable::Service for all other actions:

let mut map = HashMap::new();
map.insert("_", ServiceRunnable::Service("nginx")); // <-- "_" is the default key
map.insert("status", ServiceRunnable::Command("/usr/bin/zabbix_get -k 'proc.num[nginx,nginx]'"));
let service = Service::new_map(map, None);

Note that when mapping actions to ServiceRunnable::Commands, the action name is not appended to the command, unless it is the default ServiceRunnable:

let mut map = HashMap::new();
map.insert("start", ServiceRunnable::Command("/usr/bin/start_svc"));
map.insert("kill", ServiceRunnable::Command("killall my_svc"));
map.insert("_", ServiceRunnable::Command("/usr/bin/svc_ctl"));
let service = Service::new_map(map, None);
service.action(&mut host, "start").unwrap(); // <-- Calls "/usr/bin/start_svc"
service.action(&mut host, "status").unwrap(); // <-- Calls "/usr/bin/svc_ctl status"

Mapping Actions to Other Actions

In an effort to standardise actions across platforms and daemons, it is sometimes advantageous to map one action to another. For example, you can use action maps to abstract complex flags, which makes your code more readable:

let mut map = HashMap::new();
map.insert("start", "-c /etc/my_svc.conf");
map.insert("stop", "-t");
let service = Service::new_service(ServiceRunnable::Command("/usr/local/bin/my_svc"), Some(map));
service.action(&mut host, "start").unwrap(); // <-- Calls "/usr/local/bin/my_svc -c /etc/my_svc.conf"

You can also use action maps to assist with cross-platform compatibility:

let mut map = HashMap::new();
if needstr!(host.data_owned() => "/_telemetry/os/platform").unwrap() == "centos" {
    map.insert("reload", "restart");
}
let service = Service::new_service(ServiceRunnable::Command("/usr/bin/my_svc"), Some(map));
service.action(&mut host, "reload").unwrap(); // <-- Calls "/usr/bin/my_svc restart" on CentOS

Methods

impl Service

fn new_service<'a>(
    runnable: ServiceRunnable<'a>,
    mapped_actions: Option<HashMap<&'a str, &'a str>>
) -> Service

Create a new Service with a single ServiceRunnable.

let service = Service::new_service(ServiceRunnable::Service("service_name"), None);

fn new_map<'a>(
    actions: HashMap<&'a str, ServiceRunnable<'a>>,
    mapped_actions: Option<HashMap<&'a str, &'a str>>
) -> Service

Create a new Service with multiple ServiceRunnables.

let mut map = HashMap::new();
map.insert("start", ServiceRunnable::Command("/usr/local/bin/nginx"));
map.insert("stop", ServiceRunnable::Command("killall \"nginx: master process nginx\""));
let service = Service::new_map(map, None);

fn action(
    &self,
    host: &mut Host,
    action: &str
) -> Result<Option<CommandResult>, Error>

Run a service action, e.g. "start" or "stop".

If the function returns Some, the action was required to run in order to get the host into the required state. If the function returns None, the host is already in the required state.

 let service = Service::new_service(ServiceRunnable::Command("/usr/bin/nginx"), None);
 service.action(&mut host, "start").unwrap();