Crate service_manager

Expand description

§Service Manager

Rust library that provides an interface towards working with the following service management platforms:

sc.exe for use with Window Service (Windows)
Winsw (Windows)
Launchd (MacOS)
systemd (Linux)
OpenRC (Linux)
rc.d (FreeBSD)

Requires Rust 1.58.1 or higher!

§Installation

Add the following to your Cargo.toml:

[dependencies]
service-manager = "0.8"

§Examples

§Generic service management

This crate provides a mechanism to detect and use the default service management platform of the current operating system. Each ServiceManager instance provides four key methods:

install - will install the service specified by a given context
uninstall - will uninstall the service specified by a given context
start - will start an installed service specified by a given context
stop - will stop a running service specified by a given context

use service_manager::*;
use std::ffi::OsString;
use std::path::PathBuf;

// Create a label for our service
let label: ServiceLabel = "com.example.my-service".parse().unwrap();

// Get generic service by detecting what is available on the platform
let manager = <dyn ServiceManager>::native()
    .expect("Failed to detect management platform");

// Install our service using the underlying service management platform
manager.install(ServiceInstallCtx {
    label: label.clone(),
    program: PathBuf::from("path/to/my-service-executable"),
    args: vec![OsString::from("--some-arg")],
    contents: None, // Optional String for system-specific service content.
    username: None, // Optional String for alternative user to run service.
    working_directory: None, // Optional String for the working directory for the service process.
    environment: None, // Optional list of environment variables to supply the service process.
    autostart: true, // Specify whether the service should automatically start upon OS reboot.
    disable_restart_on_failure: false, // Services restart on crash by default.
}).expect("Failed to install");

// Start our service using the underlying service management platform
manager.start(ServiceStartCtx {
    label: label.clone()
}).expect("Failed to start");

// Stop our service using the underlying service management platform
manager.stop(ServiceStopCtx {
    label: label.clone()
}).expect("Failed to stop");

// Uninstall our service using the underlying service management platform
manager.uninstall(ServiceUninstallCtx {
    label: label.clone()
}).expect("Failed to stop");

§User-level service management

By default, service management platforms will interact with system-level services; however, some service management platforms like systemd and launchd support user-level services. To interact with services at the user level, you configure your manager using the generic ServiceManager::set_level function.

use service_manager::*;

// Create a label for our service
let label: ServiceLabel = "com.example.my-service".parse().unwrap();

// Get generic service by detecting what is available on the platform
let mut manager = <dyn ServiceManager>::native()
    .expect("Failed to detect management platform");

// Update our manager to work with user-level services
manager.set_level(ServiceLevel::User)
    .expect("Service manager does not support user-level services");

// Continue operating as usual via install/uninstall/start/stop
// ...

§Specific service manager configurations

There are times where you need more control over the configuration of a service tied to a specific platform. To that end, you can create the service manager explicitly and set configuration properties appropriately.

use service_manager::*;
use std::ffi::OsString;
use std::path::PathBuf;

// Create a label for our service
let label: ServiceLabel = "com.example.my-service".parse().unwrap();

// Instantiate a specific service manager
let mut manager = LaunchdServiceManager::system();

// Update an install configuration property where installing a service
// will NOT add the KeepAlive flag
manager.config.install.keep_alive = false;

// Install our service using the explicit service manager
manager.install(ServiceInstallCtx {
    label: label.clone(),
    program: PathBuf::from("path/to/my-service-executable"),
    args: vec![OsString::from("--some-arg")],
    contents: None, // Optional String for system-specific service content.
    username: None, // Optional String for alternative user to run service.
    working_directory: None, // Optional String for the working directory for the service process.
    environment: None, // Optional list of environment variables to supply the service process.
    autostart: true, // Specify whether the service should automatically start upon OS reboot.
    disable_restart_on_failure: false, // Services restart on crash by default.
}).expect("Failed to install");

§Running tests

For testing purposes, we use a separate crate called system-tests and execute singular tests based on desired platform and level. From the root of the repository, execute the following to run a systemd user test:

cargo test -p system-tests systemd_for_user -- --nocapture

Separately, run a systemd system test using the following (notice using of sudo -E to maintain permissions needed for system-level installation):

sudo -E cargo test -p system-tests systemd_for_system -- --nocapture

§License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.

Structs§

LaunchdConfig: Configuration settings tied to launchd services
LaunchdInstallConfig: Configuration settings tied to launchd services during installation
LaunchdServiceManager: Implementation of ServiceManager for MacOS’s Launchd
OpenRcConfig: Configuration settings tied to OpenRC services
OpenRcServiceManager: Implementation of ServiceManager for Linux’s OpenRC
RcdConfig: Configuration settings tied to rc.d services
RcdServiceManager: Implementation of ServiceManager for FreeBSD’s rc.d
ScConfig: Configuration settings tied to sc.exe services
ScInstallConfig: Configuration settings tied to sc.exe services during installation
ScServiceManager: Implementation of ServiceManager for Window Service leveraging sc.exe
ServiceInstallCtx: Context provided to the install function of ServiceManager
ServiceLabel: Label describing the service (e.g. org.example.my_application
ServiceStartCtx: Context provided to the start function of ServiceManager
ServiceStatusCtx: Context provided to the status function of ServiceManager
ServiceStopCtx: Context provided to the stop function of ServiceManager
ServiceUninstallCtx: Context provided to the uninstall function of ServiceManager
SystemdConfig: Configuration settings tied to systemd services
SystemdInstallConfig: Configuration settings tied to systemd services during installation
SystemdServiceManager: Implementation of ServiceManager for Linux’s systemd
WinSwConfig: Service configuration
WinSwInstallConfig
WinSwOptionsConfig
WinSwServiceManager: Service manager implementation

Enums§

ServiceLevel: Represents whether a service is system-wide or user-level
ServiceManagerKind: Represents the kind of service manager
ServiceStatus: Represents the status of a service
SystemdServiceRestartType
TypedServiceManager: Represents an implementation of a known ServiceManager
WinSwOnFailureAction
WinSwPriority
WinSwStartType
WindowsErrorSeverity
WindowsServiceType
WindowsStartType

Traits§

ServiceManager: Interface for a service manager

Functions§

native_service_manager: Attempts to select a native service manager for the current operating system1
systemd_global_dir_path
systemd_user_dir_path

Crate service_managerCopy item path