Struct Ansible

pub struct Ansible { /* private fields */ }

Main Ansible command builder and executor.

The Ansible struct provides a fluent interface for building and executing Ansible ad-hoc commands. It supports all major Ansible modules and provides type-safe configuration options.

Examples

Basic Usage

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .add_host("web01")
    .set_inventory("hosts.yml");

// Execute a ping
let result = ansible.ping()?;
println!("Ping result: {}", result);

Module Execution

use ansible::{Ansible, Module, PackageState};

let mut ansible = Ansible::default();
ansible.add_host("all");

// Install a package
let module = Module::package("nginx", PackageState::Present);
let result = ansible.run(module)?;

Environment Configuration

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .set_system_envs()
    .filter_envs(["HOME", "PATH", "USER"]);

Implementations

impl Ansible

pub fn set_system_envs(&mut self) -> &mut Self

Set environment variables from the current system environment.

This method copies all environment variables from the current process to be passed to the Ansible command. This is useful for ensuring Ansible has access to necessary environment variables like PATH, HOME, etc.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.set_system_envs();

pub fn filter_envs<T, S>(&mut self, iter: T) -> &mut Self

where T: IntoIterator<Item = S>, S: AsRef<OsStr> + Display,

Filter environment variables to only include specified keys.

This method is useful for limiting which environment variables are passed to Ansible commands, which can improve security and reduce potential side effects.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .set_system_envs()
    .filter_envs(["HOME", "PATH", "USER"]);

pub fn add_env( &mut self, key: impl Into<String>, value: impl Into<String>, ) -> &mut Self

Add a single environment variable.

This method adds or overwrites an environment variable that will be passed to the Ansible command.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .add_env("ANSIBLE_HOST_KEY_CHECKING", "False")
    .add_env("ANSIBLE_STDOUT_CALLBACK", "json");

pub fn arg<S: AsRef<OsStr> + Display>(&mut self, arg: S) -> &mut Self

Add a single command-line argument.

This method adds a raw command-line argument to the Ansible command. Use this for options not covered by specific methods.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .arg("--verbose")
    .arg("--check");

pub fn args<T, S>(&mut self, args: T) -> &mut Self

where T: IntoIterator<Item = S>, S: AsRef<OsStr> + Display,

Add multiple command-line arguments.

This method adds multiple raw command-line arguments to the Ansible command.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.args(["--verbose", "--check", "--diff"]);

pub fn add_host<S: AsRef<OsStr> + Display>(&mut self, host: S) -> &mut Self

Add a single host or host pattern to the target list.

This method adds a host or host pattern to target with Ansible commands. You can specify individual hosts, groups, or patterns.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible
    .add_host("web01")
    .add_host("db*")
    .add_host("all");

pub fn add_hosts<T, S>(&mut self, hosts: T) -> &mut Self

where T: IntoIterator<Item = S>, S: AsRef<OsStr> + Display,

Add multiple hosts or host patterns to the target list.

This method adds multiple hosts or host patterns at once.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_hosts(["web01", "web02", "db*"]);

pub fn clear_hosts(&mut self) -> &mut Self

Clear all hosts from the target list.

This method removes all previously added hosts and patterns.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("web01").add_host("web02");
ansible.clear_hosts(); // Now no hosts are targeted

pub fn set_inventory(&mut self, s: &str) -> &mut Self

Set the inventory file or directory.

This method specifies the inventory file or directory to use for host and group information.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.set_inventory("hosts.yml");
ansible.set_inventory("/etc/ansible/hosts");
ansible.set_inventory("production");

pub fn set_output_json(&mut self) -> &mut Self

Configure output to use JSON format.

This method sets environment variables to configure Ansible to output results in JSON format, which is useful for programmatic processing.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.set_output_json();

pub fn run(&self, m: Module) -> Result<String>

Execute an Ansible module with the current configuration.

This is the core method that executes Ansible commands. It takes a Module and executes it with the current host targets, inventory, and other configuration options.

Arguments

• m - The module to execute

Returns

Returns the combined stdout and stderr output from the Ansible command.

Errors

Returns an error if:

• No module is specified (Module::None)
• The Ansible command fails to execute
• The command returns a non-zero exit code

Examples

use ansible::{Ansible, Module};

let mut ansible = Ansible::default();
ansible.add_host("localhost");

let result = ansible.run(Module::Ping)?;
println!("Ping result: {}", result);

pub fn shell(&self, command: impl Into<String>) -> Result<String>

Execute a shell command on target hosts.

This method uses the shell module to execute commands with shell processing, allowing for pipes, redirects, and variable expansion.

Arguments

• command - The shell command to execute

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("localhost");

let result = ansible.shell("ps aux | grep nginx")?;
println!("Process list: {}", result);

Security Note

Be careful with shell injection when using user input. Consider using command for simple command execution.

pub fn command(&self, command: impl Into<String>) -> Result<String>

Execute a command on target hosts without shell processing.

This method uses the command module to execute commands safely without shell processing, making it safer for user input.

Arguments

• command - The command to execute

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("localhost");

let result = ansible.command("ls -la /opt")?;
println!("Directory listing: {}", result);

pub fn script(&self, script_path: impl Into<String>) -> Result<String>

Execute a local script on target hosts.

This method transfers a local script to target hosts and executes it.

Arguments

• script_path - Path to the local script file

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("localhost");

let result = ansible.script("./deploy.sh")?;
println!("Script output: {}", result);

pub fn ping(&self) -> Result<String>

Test connectivity to target hosts using the ping module.

This method uses the ping module to test basic connectivity and authentication to target hosts.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("all");

let result = ansible.ping()?;
println!("Ping result: {}", result);

pub fn setup(&self) -> Result<String>

Gather system facts from target hosts using the setup module.

This method collects detailed information about target hosts including hardware, network, and operating system details.

Examples

use ansible::Ansible;

let mut ansible = Ansible::default();
ansible.add_host("localhost").set_output_json();

let facts = ansible.setup()?;
println!("System facts: {}", facts);

pub fn copy( &self, src: impl Into<String>, dest: impl Into<String>, ) -> Result<String>

Copy files to remote hosts

pub fn package( &self, name: impl Into<String>, state: PackageState, ) -> Result<String>

Manage packages

pub fn service( &self, name: impl Into<String>, state: ServiceState, ) -> Result<String>

Manage services

pub fn file(&self, path: impl Into<String>, state: FileState) -> Result<String>

Manage files and directories

pub fn template( &self, src: impl Into<String>, dest: impl Into<String>, ) -> Result<String>

Template files

pub fn user(&self, name: impl Into<String>, state: UserState) -> Result<String>

Manage users

pub fn group( &self, name: impl Into<String>, state: GroupState, ) -> Result<String>

Manage groups

pub fn raw(&self, command: impl Into<String>) -> Result<String>

Execute raw commands (bypasses module system)

pub fn fetch( &self, src: impl Into<String>, dest: impl Into<String>, ) -> Result<String>

Fetch files from remote hosts

pub fn synchronize( &self, src: impl Into<String>, dest: impl Into<String>, ) -> Result<String>

Synchronize files and directories

pub fn git( &self, repo: impl Into<String>, dest: impl Into<String>, ) -> Result<String>

Manage Git repositories

pub fn cron( &self, name: impl Into<String>, job: impl Into<String>, ) -> Result<String>

Manage cron jobs

pub fn mount( &self, path: impl Into<String>, src: impl Into<String>, fstype: impl Into<String>, ) -> Result<String>

Mount filesystems

pub fn systemd( &self, name: impl Into<String>, state: ServiceState, ) -> Result<String>

Manage systemd services

Trait Implementations

impl Clone for Ansible

fn clone(&self) -> Ansible

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ansible

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Ansible

fn default() -> Self

Returns the “default value” for a type.

impl Display for Ansible

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.