Help language development. Donate to The Perl Foundation

Sparrowdo cpan:MELEZHIK last updated on 2018-08-14



Configuration management tool based on sparrow plugins system.

Build status

Build Status


Getting started

If you're just looking to get started with Sparrowdo, check out Tyil's tutorial on Sparrowdo. This covers the absolute basics, including getting Perl 6 to run on your machine, installing Sparrowdo and getting your first scenario up and running.

In depth usage guide

There are 3 essential things in Sparrowdo:

Core DSL

Core DSL is probably the easiest way to start using Sparrowdo right away. It offers some high level functions to deal with the most common configuration tasks, like a creation of directories or users, populating configuration files from templates or starting services.

$ cat sparrowfile

user 'zookeeper';

group 'birds';

directory '/var/data/avifauna/greetings/', %( owner => 'zookeeper' );

file-create '/var/data/avifauna/greetings/sparrow.txt', %( 
    owner => 'zookeeper',
    group => 'birds', 
    mode  => '0644', 
    content => 'I am little but I am smart'

service-start 'nginx';

package-install ('nano', 'ncdu', 'mc' );

Read the core-dsl doc to get familiar with core-dsl functions available in the current sparrowdo version.

Plugins DSL

Under the hood the plugins DSL is just a "call"(*) of some sparrow plugins with parameters.

Thus, if you want a direct access to sparrow plugins API you use the plugins DSL.

Examples above could be rewritten in the terms of the low level plugins API:

$ cat sparrowfile

task-run  %(
  task        => 'create zookeeper user',
  plugin      => 'user',
  parameters  => %( 
    action => 'create' , 
    name => 'zookeeper'

task-run  %(
  task        => 'create birds group',
  plugin      => 'group',
  parameters  => %( 
    action => 'create' , 
    name => 'birds'

# the following code will use the short form of running tasks - task-run($task_desc, $plugin_name, %parameters)

task-run 'create greetings directory', 'directory', %( 
  action  => 'create' , 
  path    => '/var/data/avifauna/greetings',
  owner   => 'zookeeper'

task-run 'create sparrow greeting file', 'file', %(
  action      => 'create',
  target      => '/var/data/avifauna/greetings/sparrow.txt',
  owner       => 'zookeeper',
  group       => 'birds' 
  mode        => '0644',
  content     => 'I am little but I am smart'

task-run 'start nginx web server', 'service',  %(
  action      => 'start',
  service     => 'nginx'

task-run 'install some handy packages', 'package-generic', %( list  => 'nano ncdu mc' );

(*) Not that accurate. Technically speaking plugins DSL functions just return a JSON data to serialize sparrow plugins with its binded parameters ( so called sparrow tasks ) and after that the data is copied ( by scp ) to the target host, where it is finally executed by sparrow client.

Reasons you may prefer plugins DSL:

Core DSL vs Plugins DSL

Core DSL is a kinda high level adapter with addition of some "syntax sugar" to make your code terse and effective. It is also important that as the core DSL methods are Perl6 functions, you take advantage of input parameters validation. However core DSL is limited. Not every sparrow plugin has related core DSL method.

So it's up to you whether to use the core DSL or low level plugins API.

Once I've found some sparrow plugin very common and highly useful I will the proper core DSL binded to the plugin. In case you need core DSL wrappers for the new plugins - let me know!

Here is the list of core DSL functions available in the current Sparrowdo version.

Running sparrowdo scenario

Now, once we've created a sparrowfile let's run the scenario on some remote host:

$ sparrowdo --host=


Here is the visual presentation of sparrowdo system design:

sparrowdo system design

Master host

Master host is a dedicated server where you "push" sparrow tasks from for being executed on remote hosts.

Sparrowdo client should be installed at the master host:

$ zef install Sparrowdo

Sparrowdo acts over ssh invoking sparrow client with input json data generated by.

Sparrow client in turn downloads and installs the plugins and create plugins configuration - sparrow tasks. Finally tasks are executed converging the server to desired configuration.

A list of available sparrow plugins could be found here -

Remote hosts

Remote hosts are configured by sparrow client which sets up and executes sparrow tasks.

Sparrow client have to be installed on the remote host.

$ cpanm Sparrow

A minimal none Perl dependencies also should be satisfied - curl utility. Sparrow manages its index files and upload plugins by using curl:

$ yum install curl

It is possible to automate the process of sparrow client installation on the remote host, see the bootstrap section for details.

SSH/User setup

An assumption is made that ssh user you run sparrowdo with ( see --ssh_user command line parameter also ) has:


You can use password authentication with --password command line parameter or ( more preferred ) via shell environment SSHPASS. See info for --password parameter below.

Advanced usage

Running private plugins

You should use set_spl(%hash) function to set up the private plugins index file:

$ cat sparrowfile

set_spl %(
    package-generic-dev => '',
    df-check-dev => ''

task-run 'install my packages', 'package-generic-dev', %( list => 'cpanminus git-core' );

task-run 'check my disk', 'df-check-dev';

Sparrowdo client command line parameters


Prints brief usage info.


Sets the remote host's IP address or hostname. This is mandatory parameter. Default value is


Sets the name of running docker container, use this if you want to run sparrow tasks against docker.


Alternative location of sparrowfile.

If --sparrowfile is not set, sparrowdo will look for the file named sparrowfile in the current working directory.

$ sparrowdo --sparrowfile=~/sparrowfiles/sparrowfile.pl6


Sets http_proxy environment variable on the remote host.


Sets https_proxy environment variable on the remote host.


Sets user for the ssh connection to the remote host.


Your password for authentication to the remote host. Also you can use shell environment variable SSHPASS, e.g:

$ export SSHPASS=12345; sparrowdo ...

You must install sshpass to use this feature.


Selects the file from which the identity (private key) for public key authentication is read.

Is equal to -i parameter of ssh client.


Sets ssh port for the ssh connection to remote host. Default value is 22.


Sets alternative location for sparrow client root directory. Default value is /opt/sparrow;

Optional parameter.


If set to true - do not initiate ssh command under sudo, just as is. Default value is false - use sudo.

Optional parameter.


If set to true - only compiles scenarios and don't run anything on the remote host. Optional parameter.


If set to true - do not run sparrow index update command on the remote host.

This could be useful if you are not going to install new versions of sparrow plugins on the remote host and want to save the time as index operation is quite time consuming.

Optional parameter.


If set to true - disable color output of sparrowdo client.


Sets format for reports. One of possible values:

Default value is default

Optional parameter.


Remove temporary/cache files left by sparrow run. Set this parameter to True if you want to keep this files, which might be useful when troubleshooting.

Default value is True ( remove cache files )

Optional parameter.


Runs a sparrowdo module instead of executing scenario from sparrowfile. For example:

$ sparrowdo --host= --module_run=Nginx

You can use task_run notation to pass parameter to modules:

--module_run=module-name@p1=v1,p2=v2,p3=v3 ...

Where module-name - module name. p1, p2 ... - module parameters (separated by ,)

For example:

$ sparrowdo --host= --module_run=Cpanm::GitHub@user=leejo,,branch=master


Runs a sparrow plugin instead of executing scenario from a sparrowfile.

For example:

$ sparrowdo --host= --task_run=df-check

You can run multiple tasks (plugins) with parameters as well:

--task_run=plg-name@p1=v1,p2=v2,... --task-run=plg-name@p1=v1,p2=v2,...

Where plg-name - plugin name. p1, p2 ... - plugins parameters (separated by ,)

For example:

$ sparrowdo --host= \
--task_run=user@name=foo \
--task_run=bash@command='id &&  pwd && uptime && ls -l && ps uax|grep nginx|grep -v grep',user=foo \


Sets a verbose mode ( low level information will be printed at console ).


This option sets the custom sparrow repository for being used when sparrow runs on the remote machine.

For example:



This option sets the current working directory for the process which executes sparrow scenarios.

Optional, no default values.


Export ssh configuration from vagrant host and run sparrowdo against it.


$ sparrowdo --vagrant # assuming we are in a working directory with Vagrantfile
                      # exporting ssh configuration for "current" vagrant machine

$ sparrowdo --vagrant --vagrant_id=6951606  # exporting ssh configuration 
                                            # from vagrant machine with ID `6951606`


Set sparrowdo variables.

Use key=value format to set variables. Variables defined at configuration file are overridden by this command line values.

You can use multiple --var constructs:

--var='color=red' --var='color=green' --var='color=blue'

Run sparrowdo in local mode

In case you need to run sparrowdo on localhost add --local_mode flag and get things done locally, not remotely:

$ sparrowdo --local_mode

Sparrowdo configuration via ini file

You may pass some sparrowdo client options via ini files at ~/sparrowdo.ini.

Here is the list of available options:

For example:

no_index_update = 1
verbose         = 1
repo            =
format          = production


One may use bootstrap mode to install sparrow client on the remote host first:

$ sparrowdo --host= --bootstrap


The bootstrap feature is still experimental and poorly tested, I urge you not to run bootstrap on production, valuable hosts.

Sparrowdo modules

Sparrowdo modules are collections of sparrow tasks.

They are very similar to the sparrow task boxes, with some differences though:

An example of sparrowdo module:

use v6;

unit module Sparrowdo::Nginx;

use Sparrowdo;

our sub tasks (%args) {

  task-run 'install nginx', 'package-generic', %( list => 'nginx' );

  task-run 'enable nginx', 'service', %(
    service => 'nginx', 
    action => 'enable'

  task-run task => 'start nginx', 'service', %( 
    service => 'nginx', 
    action => 'start' 


Later on, in your sparrowfile you may have this:

$ cat sparrowfile

module_run 'Nginx';

You may pass parameters to a sparrowdo module:

module_run 'Nginx', port => 80;

In module's definition one access the parameters as:

our sub tasks (%args) {

    say %args<port>;


The module naming convention is:

Sparrowdo::Foo::Bar ---> module_run Foo::Bar

module_run($module_name) function loads module Sparrowdo::$module_name at runtime and calls function tasks defined in the module's global context.

Helper functions

Module developers could rely on some helper functions, when creating their modules.

This function returns the remote server OS name.

For example:

if target_os() ~~ m/centos/ {
  task-run 'install epel-release', 'package-generic', %( list => 'epel-release' );

The list of OS names is provided by target_os() function:


This function returns the remote server hostname.

The input_params function returns command line parameter one provides when run sparrowdo client.

For example:

task-run  %('install Moose', 'cpan-package', %( 
  list => 'Moose',
  http_proxy => input_params('HttpProxy'), 
  https_proxy => input_params('HttpsProxy'), 

This is the list of arguments valid for the input_params function:


See also the sparrowdo client command line parameters section.

Scenarios configuration

There is no "magic" way to load a configuration into sparrowdo scenarios. You are free to choose any Perl6 modules you want to deal with a configuration data.

But if config.pl6 file exists at the current working directory it will be loaded via EVALFILE at the beginning of scenario.

For example:

$ cat config.pl6

  user         => 'foo',
  install-base => '/opt/foo/bar'

Later on in the scenario you may access config data via config function:

$ cat sparrowfile

my $user         = config<user>;
my $install-base = config<install-base>;

See also variables section.

Environment variables

Enable some sparrowdo debug messages printed in a console.

Sets format for reports, see also --format option of sparrowdo client.


Aleksei Melezhik

Home page


Copyright 2015 Alexey Melezhik.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See also


To God as the One Who inspires me to do my job!