{"id":16301135,"url":"https://github.com/melezhik/sparrow","last_synced_at":"2025-03-20T21:31:04.034Z","repository":{"id":55041430,"uuid":"46789125","full_name":"melezhik/sparrow","owner":"melezhik","description":"Sparrow - script distribution platform for Linux OS","archived":false,"fork":false,"pushed_at":"2021-01-13T14:39:08.000Z","size":829,"stargazers_count":77,"open_issues_count":3,"forks_count":6,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-11T20:53:57.170Z","etag":null,"topics":["automation","cli","outthentic-plugins","sparrow","sparrow-client","sparrow-plugin","sparrow-task","task-runner"],"latest_commit_sha":null,"homepage":"https://sparrowhub.org","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/melezhik.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-24T12:03:28.000Z","updated_at":"2024-04-08T20:24:49.000Z","dependencies_parsed_at":"2022-08-14T09:50:52.435Z","dependency_job_id":null,"html_url":"https://github.com/melezhik/sparrow","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2Fsparrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2Fsparrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2Fsparrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2Fsparrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/melezhik","download_url":"https://codeload.github.com/melezhik/sparrow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244084228,"owners_count":20395515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","outthentic-plugins","sparrow","sparrow-client","sparrow-plugin","sparrow-task","task-runner"],"created_at":"2024-10-10T20:53:55.904Z","updated_at":"2025-03-20T21:31:03.515Z","avatar_url":"https://github.com/melezhik.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nSparrow - multipurpose scenarios manager.\n\n# ATTENTION\n\n***This is Sparrow for Perl5 and it is no longer supported and deprecated.*** \n\n***If you're looking for Sparrow6 - Raku version of Sparrow, see [Sparrow6](https://github.com/melezhik/Sparrow6)***\n\n***If you still want to use this version follow [Sparrow](https://metacpan.org/pod/Sparrow)\nfor the latest CPAN release. However, pay attention that:***\n\n* ***All [Sparrow plugins](https://github.com/melezhik/sparrow-plugins) are only compatible with Sparrow6 version.*** \n* ***SparrowHub repository is abolished and no longer exists***\n\n\n\n# SYNOPSIS\n\n# Install\n\n    $ sudo yum install git # only required for installing private plugins\n    $ sudo yum install curl\n    $ cpanm Sparrow\n\n# Build statuses\n\n[![Build Status](https://travis-ci.org/melezhik/sparrow.svg)](https://travis-ci.org/melezhik/sparrow)\n[![Build status](https://ci.appveyor.com/api/projects/status/hdowsd2jvmy0x3ae?svg=true)](https://ci.appveyor.com/project/melezhik/sparrow)\n\n# Sparrow plugins\n\nSparrow plugins are shareable multipurpose scenarios distributed via central repository - [SparrowHub](https://sparrowhub.org).\nEvery single plugin represents a various scripts to solve a specific task. Plugins are easily installed, configured and run on\ndedicated servers with the help of sparrow console client. \n\nThe notion of sparrow plugins is very close to the conception of CPAN modules in Perl or Ruby gems in Ruby.\nIt's just a small suites of scripts to solve a specific tasks.\n\nSupported plugin types.\n\nSparrow supports two types of plugins depending on underlying runner to execute plugin scenarios. They are:\n\n* [Outthentic](https://github.com/melezhik/outthentic) Plugins\n\n* [SWAT](https://github.com/melezhik/swat) Plugins\n\n\nTo find a specific sparrow plugin say this:\n\n    $ sparrow plg search nginx\n\nTo install a sparrow plugin say this: \n\n    $ sparrow plg install nginx-check\n\nSee [sparrow command line API](#api) below.\n \n# Sparrow client\n\n`Sparrow` is a console client to search, install, setup and run various sparrow plugins. \n\nThink about it as of `cpan client` for CPAN modules or `gem client` for Ruby gems.\n\nYou run Sparrow client by using `sparrow` command.\n\nTo print out Sparrow currently installed version, run this:\n\n    $ sparrow --version\n\n# Sparrow basic entities\n\nSparrow architecture comprises of 4 basic parts:\n\n* Plugins\n* Tasks\n* Projects\n* Task Boxes\n\n# Tasks\n\n_Task_ is configurable sparrow plugin. Some plugins does not require configuration and could be run as is,\nbut many ones require some piece of input data. Thus sparrow task is a container for:\n\n* plugin\n* plugin configuration\n\nPlugin configuration is just a text file in one of 4 formats:\n\n* [Config::General](https://metacpan.org/pod/Config::General) format - consumed by Outthentic plugins\n* YAML format - consumed by both Swat and Outthentic plugins\n* JSON format - consumed by Outthentic plugins\n* [Config::Tiny](https://metacpan.org/pod/Config::Tiny) format - consumed by Swat plugins\n\n# Projects\n\nProjects are _logical groups_ of sparrow tasks. It is convenient to split a whole list of tasks to different logical groups. \nLike some tasks for system related issues - f.e. checking [disk available space](https://sparrowhub.org/info/df-check) or inspecting [stale processes](https://sparrowhub.org/info/stale-proc-check), other tasks for\nweb services related issues - f.e. [checking nginx health](https://sparrowhub.org/info/nginx-check) or [monitoring http errors](https://sparrowhub.org/info/logdog) in web server logs, so on. \n\n# Task Boxes\n\nSparrow tasks boxes are JSON format files to describe sequential tasks to run. \n\nYou could think about sparrow boxes as of multi tasks. Sparrow runs tasks from the box sequentially.\n\n\n# API\n\nThis is a sparrow command line API documentation.\n\n## Projects API\n\nSparrow project is a logical group of sparrow tasks. To create a project use `sparrow project create` command:\n\n**sparrow project create $project\\_name**\n\nCommand examples:\n\n    # system level tasks\n    $ sparrow project create system\n\n    # web servers related tasks\n    $ sparrow project create web-servers\n\nTo get project information say this:\n\n**sparrow project show $project\\_name**\n\nFor example:\n\n    $ sparrow project show system\n\nTo get projects list say this:\n\n**sparrow project list**\n\nTo remove project data say this:\n\n**sparrow project remove $project\\_name**\n\nFor example:\n\n    $ sparrow project remove web-servers\n\n***NOTE!*** This command will remove all project tasks as well!\n\n## Plugins API\n\nTo search available plugins use `sparrow plg search` command:\n\n**sparrow plg search $pattern**\n\nWhere $pattern is Perl regular expression pattern.\n\nExamples:\n\n  \n    # find ssh-* plugins\n    $ sparrow plg search ssh\n\n    [found sparrow plugins]\n    \n    type    name\n    \n    public  ssh-sudo-check\n    public  ssh-sudo-try\n    public  sshd-check\n    \n    # find package managers plugins\n    $ sparrow plg search package\n\n    [found sparrow plugins]\n    \n    type    name\n    \n    public  package-generic\n    \n\nTo list all available plugins say this:\n\n    $ sparrow plg search \n\n### Index API\n\nSparrow index is cached data used by sparrow to search plugins.\n\nIndex consists of two parts:\n\n* private plugins index , see [SPL file](#spl-file) section for details\n* public  plugins index, [PUBLIC PLUGINS](#public-plugins) section for details\n\nThere are two basic command to work with index:\n\n* **sparrow index summary**\n\nThis command will show timestamps and file locations for public and private index files.\n\n* **sparrow index update**\n\nThis command will fetch fresh index from SparrowHub and update local cached index.\n\nThis is very similar to what `cpan index reload` command does.\n\nYou need `sparrow index update` to get know about updates, changes of SparrowHub repository. For example\nwhen someone release new version of plugin.\n\nSee [public plugins](#public-plugins) section for details on sparrow public plugins and SparrowHub.\n\n### Installing sparrow plugins\n\n**sparrow plg install $plugin\\_name**\n\nFor example:\n\n    $ sparrow plg search  nginx        # to get know available nginx* plugins\n    $ sparrow plg install nginx-check  # to download and install a chosen plugin\n    $ sparrow plg install nginx-check --version 0.1.1 # install specific version\n\nInstalling plugin from local source:\n\n    $ cd /plg/src/ \u0026\u0026 sparrow plg install /path/to/source --local \n\nInstall plugin from local source recursively:\n\n    $ sparrow plg install /path/to/plugins --local --recursive\n\nThis command will recursively go through /path/to/plugins directory and for every directory containing \n`sparrow.json` file runs `sparrow plg install .` command.\n\nForcefully reinstall plugin\n\nUse `force` flag to reinstall local plugins:\n\n    $ sparrow plg install /path/to/source --local --recursive --force \n\n    $ sparrow plg install /path/to/plugins --local --force \n\nReinstall plugins dependencies\n\nUse `install-deps`.. It only works with public plugins:\n\n\n    $ sparrow plg install cpan-upload --install-deps\n\n\nTo see installed plugin list say this:\n\n    $ sparrow plg list\n\nTo get installed plugin information say this:\n\n**sparrow plg show $plugin\\_name**\n\nTo remove plugin installed use `sparrow plg remove` command:\n\n**sparrow plg remove $plugin\\_name**\n\nFor example:\n\n    $ sparrow plg remove df-check\n\n\n### Getting plugin man page\n\nIf plugin author supply his plugin with man page it could be shown as:\n\n**sparrow plg man $plugin\\_name**\n\nFor example:\n\n    $ sparrow plg man df-check\n\nAliase. `info` and `help` are just aliases for `plg man` command:\n\n    $ sparrow plg info df-check\n    $ sparrow plg help df-check\n\n## Tasks API\n\n### Create tasks\n\nTo create a task use `sparrow task add` command:\n\n**sparrow task add $project\\_name $task\\_name $plugin\\_name [opts]**\n\nTasks always belong to projects, so to create a task you have to create a project first if not exists.\nTasks binds a plugin with configuration, so to create a task you have to install a plugin first.\n\nCommand examples:\n\n    $ sparrow project create system\n    $ sparrow plg install df-check\n    $ sparrow task add system disk-health df-check\n\n\nOptions:\n\n* --quiet - suppress output of this command.\n\nFor example:\n\n    $ sparrow task add system disk-health df-check --quiet 1\n\n* --host - pass hostname parameter.\n\nIt's useful when create tasks for swat plugins\n\n    $ sparrow task add web nginx-check swat-nginx --host 127.0.0.1:80\n\n### Getting task list\n\nTo list all the task with projects use:\n\n**sparrow task list**\n\nYou can filter tasks out by using `--search` options:\n\n    # list tasks with project name or task name matching `database` and `production` strings\n\n    $ sparrow task list --search database --search production\n\n    # you can use Perl5 regexps in --search filters:\n\n    $ sparrow task list --search database --search '(test|dev)'\n\n\n### Run plugins\n\nThere are two ways to run sparrow plugins:\n\n* as\\_is\n\n* as tasks\n\nThe first one is simplest as it does not require creating a task at all. If you don't want provide a specific plugin configuration,\nyou may run a plugin as is using  `sparrow plg run` command:\n\n\n**sparrow plg run [ parameters ]**\n\nFor example:\n\n    $ sparrow plg run df-check\n\nParameters:\n\n* **verbose**\n\nSets verbose mode to get some extra message when running plugin \n\nThe second way requires task creation and benefits in applying specific configuration for a plugin:\n\n**sparrow task run $project\\_name $task\\_name [ parameters ]**\n\nFor example:\n\n    $ sparrow task run system disk-health\n\nSee [configuring tasks](#configuring-tasks) section on how one can configure task plugin.\n\nParameters:\n\n* **verbose**\n\n### Setting runtime parameters \n\n***NOTE!*** Runtime parameters are only supported for Outthentic plugins.\n\nIt is possible to pass _whatever_ runtime configuration parameters when running tasks or plugins:\n\n    $ sparrow plg run df-check --param threshold=60\n\n    $ sparrow task run system disk-health --param threshold=60\n\n    # or even nested and multi parameters!\n\n    $ sparrow plg run foo --param foo.bar.baz=60 --param id=100\n\nRuntime parameters override default parameters ones set in tasks configurations, see [configuring tasks](#configuring-task) section.\n\n### Setting plugin runner parameters\n\nWhen executing sparrow plugin sparrow relies on underlying runner defined by plugin type. There are two types of sparrow plugins:\n\n* Outthentic Plugins\n\n* SWAT Plugins\n\nBoth runners accept specific parameters. \n\nFor outthentic runner parameters follow [Outthentic](https://github.com/melezhik/outthentic#options) documentation. \n\nFor swat runner parameters follow [Swat](https://github.com/melezhik/swat#swat-runner) documentation.\n\nHere are some examples:\n\n    # outthentic plugins:\n    $ sparrow task run system/disk-health --format concise --purge-cache \n    $ sparrow task run system/disk-health --debug 2\n\n    # swat plugins:\n    $ sparrow task run web/nginx-check --prove -Q\n\n### Running tasks with cron\n\nWhen running tasks with cron it is handy only have an output if something goes wrong, \nf.e. if plugin failed for some reasons. Use `--cron` flag to enable this behavior:\n\n**sparrow task run $project\\_name $task\\_name --cron**\n\nRunning task with --cron flag suppress a normal output and only emit something in case of failures.\n\nExample:\n\n    $ sparrow task system disk-health --cron # pleas keep quite if disk space is ok\n\n### Configuring tasks\n\nTask configuration is a some input parameters consumed by plugin binded to task. \nUser should consult plugin documentation to get know a certain structure of configuration data to feed.\n\nSparrow supports two configuration formats:\n\n* Config::Tiny    ( Swat plugins )\n* Config::General ( Outthentic plugins )\n* YAML ( Outthentic and Swat plugins )\n* JSON ( Outthentic plugins )\n\nUse `task ini` command to set task configuration:\n\n**sparrow task ini $project\\_name $task\\_name**\n\nFor example:\n\n    $ export EDITOR=nano\n\n    # Config::General format\n\n    $ sparrow task ini system disk-health\n    # disk used threshold in %\n    threshold = 80\n\n    # JSON format\n    $ sparrow task ini system disk-health\n    {\n      \"threshold\": 80\n    }\n\n    # YAML format\n    $ sparrow task ini system disk-health\n    # disk used threshold in %\n    threshold: 80\n\nHaving this sparrow will save plugin configuration in the file related to task and will use it during task run:\n\n    $ sparrow task run system disk-health # the value of threshold is 80\n\nUser could copy existed configuration from file using `task load_ini` command:\n\n**sparrow task load_ini $project\\_name $task\\_name /path/to/ini/file**\n\nFor example:\n\n    $ sparrow task load_ini system disk-health /etc/plugins/disk.yaml # load from YAML file\n    $ sparrow task load_ini system disk-health /etc/plugins/disk.json # load from JSON file\n    $ sparrow task load_ini system disk-health /etc/plugins/disk.conf # load from Config::General file\n\nTo get task configuration use `sparrow task show` command:\n\n**sparrow task show $project\\_name $task\\_name**\n\nFor example:\n\n    $ sparrow task show system disk-health\n\n\nAlternative way to configure sparrow task is to load configuration from yaml/json file _during_ task run:\n\n    $ cat disk.yml\n\n    ---\n    threshold: 80\n\n    $ sparrow task run system disk --yaml disk.yml\n\n    $ cat disk.json\n\n    {\n      \"threshold\": 80\n    }\n\n    $ sparrow task run system disk --json disk.json\n     \nWhile `sparrow task ini/load_ini` command saves task configuration and makes it persistent,\n`sparrow task run --yaml|--json` command applies plugin configuration only for runtime and won't save it after plugin execution.\n\nFor common usage, when user runs tasks manually first approach is more convenient, \nwhile the second one is a _way automatic_, when tasks configurations are kept as yaml files\nand maintained out of sparrow scope and applied during task run.\n \n### Removing tasks\n\nUse this command to remove task from the project container:\n\n**sparrow task remove $project\\_name $task\\_name**\n\nExamples:\n\n    # remove task disk-health project system\n    $ sparrow task remove system disk-health\n\n### Alternative task names notation\n\nWhen working with task you may use an alternative task names notation:\n\n    $project_name/$task_name\n\nExamples:\n\n    $ sparrow task run system/disk\n    $ sparrow task show system/disk\n    $ sparrow task remove system/disk\n    $ sparrow task ini system/disk\n    # so on ...\n\n### Dump task configuration\n\nYou may dump task configuration using `--dump-config` flag, no action will be performed,\njust task configuration data will be printed out in JSON format:\n\n    $ sparrow task run system/disk --dump-config\n\nDump-config could be useful when copy some task configuration into other:\n\n    \n    $ sparrow task run system/disk --dump-config \u003e /tmp/system-disk.json\n    $ nano /tmp/system-disk.json\n    $ sparrow task load ini system/disk2 /tmp/system-disk.json\n\n\n### Copy task\n\nIf you need to copy existed task to another project use `task copy` command:\n\n***sparrow task copy project1 task project2 task2***\n\nThis command copies task `task1` from project `project1` to project named `project2`\nand give it a name `task2`\n\nYou can use alternative task notation here:\n\n    $ sparrow task copy project1/task1 project2/task2\n\n### Save/Restore tasks\n\nTo port tasks from one server to another use `save|restore` command:\n\n    $ sparrow task save /var/data/tasks\n\n    $ sparrow task restore /var/data/tasks\n\n**sparrow task save /path/to/tasks/dir**\n\nSparrow `task save` command accept path to directory where existing tasks get dumped and saved to.\n\n**sparrow task restore /path/to/tasks/dir**\n\nLikewise sparrow `task restore` command accept path to directory with tasks to restore.\n\n`Merge` option.\n\nBy default `sparrow task save` remove existing data ( if found ) from target directory. You disable this\nbehavior by passing `--merge` option:\n\n    $ sparrow task save /var/data/tasks --merge # add currents tasks to existed in  /var/data/tasks\n\nIgnore tasks.\n\nYou can omit some project/tasks from resulted save using `task.ignore` file:\n\n\n    $ nano ~/task.ignore\n\n    project1/task1\n    project2/task2\n\nThis will exclude the project1/task2 and project2/task2 tasks from resulted save. You can use regexp here:\n\n    $ nano ~/task.ignore\n\n    project1/.* # any tasks from project1\n    project2/task[2-9] # tasks 2 .. 9 from project2\n\nThe format of task ignore file:\n\n    project_name/task_name\n\nWhere `project_name` and `task_name` could be full names or regexps.\n\n\nYou may specify alternative location for task ignore file using `--ignore` option:\n\n\n    $ sparrow task save /var/data/tasks --ignore /etc/task.ignore\n\n\nThe default location for task ignore file is `~/task.ignore`\n\n\nOther options:\n\n- `--quiet` - makes output less verbose\n\n\n## Task boxes API\n\nRun task box - collection of sparrow tasks.\n\n**sparrow box run $path [opts]**\n\nWhere $path is the path to task box specification file ( json or yaml format). \n\n## The structure of task box specification file ( outthentic plugins ):\n\nJSON:\n\n    [\n\n      { // task1\n        \"task\" : \"task1_name\",\n        \"plugin\" : \"plugin_name\",\n        \"data\" : { // plugin parameters\n            \"param1\" : \"value1\",\n            \"param2\" : \"value2\"\n        }\n      },\n      { // task2\n        \"task\" : \"task2_name\",\n        \"plugin\" : \"plugin_name\",\n        \"data\" : { // plugin parameters\n            \"param1\" : \"value1\",\n            \"param2\" : \"value2\"\n        }\n      }\n      // so on\n    ]\n\nYAML:\n\n    ---\n    # task1\n    - task: task1_name\n      plugin: plugin name\n      data:\n        param1: value1\n        param2: value2\n    # task2\n    - task: task2_name\n      plugin: plugin_name\n      data:\n        param1: value1\n        param2: value2\n      # so on\n  \nCommand example:\n\n    $ sparrow box run /var/sparrow/boxes/nginx.json\n\n    $ sparrow box run /var/sparrow/boxes/nginx.yaml\n\n\nTask box specification file example:\n\nJSON:\n\n    [\n\n      {\n        \"task\" : \"install favorite packages\",\n        \"plugin\" : \"package_generic\",\n        \"data\" : {\n          \"list\" : \"nano curl mc hunspell\"\n        }\n      },\n      {\n        \"task\" : \"setup git\",\n        \"plugin\" : \"git-base\",\n        \"data\" : {\n          \"email\" : \"melezhik@gmail.com\", \"name\" : \"Alexey Melezhik\"\n          \n        }\n      }\n\n    ]\n\nYAML:\n\n    ---\n    - task: disk check\n      plugin: df-check\n      data:\n        threshold: 95\n    - task: disk check\n      plugin: df-check\n      data:\n        threshold: 95\n    - task: test plugin\n      plugin: foo-generic\n      data: {}\n    - task: test ruby plugin\n      plugin: ruby-test\n      data: {}\n    \n## The structure of tasks box specification file ( swat plugins ):\n\n\nJSON:\n\n    [\n      // task1\n      {\n        \"task\" : \"task1_name\",\n        \"plugin\" : \"plugin_name\",\n        \"type\" : \"swat\",\n        \"host\" : \"http host\"\n      },\n      // task2\n      {\n        \"task\" : \"task2_name\",\n        \"plugin\" : \"plugin_name\",\n        \"type\" : \"swat\",\n        \"host\" : \"http host\"\n      }\n      // so on\n    ]\n\n\nYAML:\n\n    ---\n    # task1\n    - task: task1_name\n      plugin: plugin_name\n      type: swat\n      host: http host\n    # task2\n    - task: task2_name\n      plugin: plugin_name\n      type: swat\n      host: http host\n    # so on\n    \n## Sparrow box run parameters\n\nTo make command output less verbose ( suppress some details ) use `--mode quiet` option:\n\n    $ sparrow box run /path/to/my/box/ --mode quiet\n\n# Sparrow plugins\n\nSparrow plugins are shareable multipurpose scenarios installed from remote sources.\n\nThere are two type of sparrow plugins:\n\n* public plugins are provided by [SparrowHub](https://sparrowhub.org/) community repository and considered as public access.\n\n* private plugins are provided by internal or external git repositories and _not necessary_ considered as public access.\n\nBoth public and private plugins are installed with help of sparrow client:\n\n**sparrow plg install plugin_name**\n\n## Public plugins\n\nThe public plugins features:\n\n* they are kept in a central place called [SparrowHub](https://sparrowhub.org/) - community plugins repository.\n\n* they are versioned so you may install various version of a one plugin.\n\n \n## Private plugins\n\nPrivate plugins are ones created by you and not supposed to be accessed publicly.\n\nThe private plugins features:\n\n* they are kept in arbitrary remote git repositories ( public or private ones )\n\n* they are not versioned, a simple \\`git clone/pull' command is executed to install/update a plugin\n\n* private plugins could be used by two methods:\n\n1) by SPL file\n2) by custom sparrow repository ( aka remote SPL file )\n\n### SPL file\n\nSPL file is located at `\\~/sparrow.list' and contains lines in the following format:\n\n*$plugin\\_name $git\\_repo\\_url*\n\nWhere:\n\n* git\\_repo\\_url\n\nIs a remote git repository URL\n\n* plugin\\_name\n\nA name of your sparrow plugin, could be arbitrary name but see restriction notice concerning public plugin names.\n\nExample entries:\n\n    package-generic   https://github.com/melezhik/package-generic.git\n\nOnce you add a proper entries into SPL file you may list and install a private plugins:\n\n    $ sparrow index update\n    $ sparrow plg show package-generic\n\n### Custom sparrow repository\n\nCustom sparrow repository is abstraction for _remote SPL file_. \n\nTo use existed custom repository add this to sparrow configuration file:\n\n    $ cat ~/sparrow.yaml\n\n    repo: 192.168.0.1:4441\n\nThis entry defines a custom repository accessible at remote host 192.168.0.1 port 4441\n\nOnce custom repository is set up you search and install custom repository plugins the same\nway as with private plugins defined at SPL file.\n\nTo run your own sparrow custom reposository use [Sparrow::Nest](https://github.com/melezhik/sparrow-nest) module.\n\n# Developing sparrow plugins\n\nAs sparrow support two types of plugins - swat and outthentic, follow a related documentation pages on\nhow to create _scenarios suites_ to gets packaged and distributes as a sparrow plugin:\n\n* For developing outthentic scenarios suites follow [Outthentic documentation](https://github.com/melezhik/outthentic).\n\n* For developing swat scenarios suites follow [Swat documentation](https://github.com/melezhik/swat).\n\n# Publishing public sparrow plugin to SparrowHub\n\nOnce a plugin is create you should do 4 simple steps:\n\n* get registered on SparrowHub and create a token\n* setup sparrowhub.json file\n* create a plugin meta file - sparrow.json\n* upload a plugin with the help of `sparrow plg upload` command\n\n## Get registered on SparrowHub\n\nGo to [https://sparrowhub.org/sign_up](https://sparrowhub.org/sign_up) and create an account\n\n## Generate a token\n\nLogin into SparrowHub, go to Profile page and hit \"Regenerate Token\" on  [https://sparrowhub.org/token](https://sparrowhub.org/token)  page.\n\n## Setup sparrowhub.json\n\nOnce your get you token, setup a sparrowhub credentials on the machine where you are going upload plugin from:\n\n    $ cat ~/sparrowhub.json\n\n    {\n        \"user\"  : \"melezhik\",\n        \"token\" : \"ADB4F4DC-9F3B-11E5-B394-D4E152C9AB83\"\n    }\n\n***NOTE!*** Another way to provide SparrowHub credentials is to set `$sph_user` and `$sph_token` environment variables:\n\n    $ export sph_user=melezhik \n    $ export sph_token=ADB4F4DC-9F3B-11E5-B394-D4E152C9AB83\n\n\n## Create a plugin meta file sparrow.json\n\nSparrow.json file holds plugin  meta information required for plugin gets uploaded to SparrowHub.\n\nCreate sparrow.json file and place it in a plugin root directory:\n\n    {\n        \"name\": \"df-check\",\n        \"version\": \"0.1.1\",\n        \"plugin_type\" : \"outthentic\"\n        \"description\" : \"elementary file system checks using df utility report \",\n        \"url\" : \"https://github.com/melezhik/df-check\",\n    }\n\nThis is description of sparrow.json parameters:\n\n* name - plugin name.\n\nOnly symbols \\`a-zA-Z1-9_-.' are allowable in plugin name. This parameter is obligatory, no default value.\n\n* version - Perl version string.\n\nThis parameter is obligatory. A detailed information concerning version syntax could be find here - [https://metacpan.org/pod/distribution/version/lib/version.pm](https://metacpan.org/pod/distribution/version/lib/version.pm)\n\n* plugin_type - one of two - `outthentic|swat` - sets plugin internal runner.\n\nThis parameter is obligatory. Default value is `outthentic`. \n\n* url - a plugin web site http URL\n\nThis parameter is optional and could be useful when you want to refer users to plugin documentation site.\n\n* description - a short description of a plugin.\n\nThis one is optional, but very appreciated.\n\n* python_version - sets Python language version.\n\nIf you install pip modules targeted for Python3 you may set python_version in sparrow.json file:\n\n    python_version : 3\n\nThat makes `sparrow plg install` command use `pip3` ( not `pip` ) to install dependencies by requirements.txt file\n\n* sparrow_version - sets minimal version of Sparrow required by plugin.\n\nThis is mostly useful for Sparrow developers. Some plugins may rely on the latest versions of Sparrow and\ncouldn't run correctly on the older versions, to avoid any confusion plugins developers may declare\na minimum version of Sparrow so that if the target machine does have it an exception will be raised\ninstead of plugin execution when `sparrow plg run` command is invoked.\n\n\n## Upload plugin\n\n* Install sparrow client on your machine\n    \n    $ cpanm Sparrow\n    \n* Go to directory where your plugin source code at and say:\n    \n    $ sparrow plg upload\n    \nThat's it!\n\nIf you want to troubleshoot upload plugin errors use `--verbose` flag, when upload plugin.\n\n# Publishing private sparrow plugins\n\nThe process is almost the same as for public plugins, except you don't have to provide SparrowHub credentials\nand gets registered as you host your plugin at remote git repository. \n\nYou have to do 3 simple steps:\n\n* create a plugin and commit it into local git repository, plugin root directory should be repository root directory\n* create plugin meta file - sparrow.json and commit it into local git repository ( sparrow.json file is the same as for public plugins )\n* push your changes into remote git repository\n\n# Declaring dependencies\n\nThis is the way how one can declare dependencies for sparrow plugins:\n\n    +----------+-------------------+\n    | Language |  File             |\n    +----------+-------------------+\n    | Perl     | cpanfile          |\n    | Ruby     | Gemfile           |\n    | Python   | requirements.txt  |\n    +----------+-------------------+\n\nYou should place a dependency file into a plugin root directory.\n\n# Disable color output\n\nTo every action you may optionally add `--nocolor` flag to disable color output:\n\n    $ sparrow plg run df-check --nocolor\n\n# Sparrow client configuration file\n\nThis file should be placed at $SPARROW_ROOT/sparrow.yaml path ( see next section on SPARROW\\_ROOT ).\n\nConfiguration options:\n\n* repo\n\nCustom sparrow repository\n\n* format \n\nDefines format for outthentic reports, possible values are: `default|concise|production`\n\n# Environment variables\n\n## SPARROW_ROOT\n\nSets sparrow root directory. \n\nIf set than sparrow will be looking sparrow index, SPL and configuration files at following locations:\n\n    $SPARROW_ROOT/sparrow.index \n    $SPARROW_ROOT/sparrow.list \n    $SPARROW_ROOT/sparrow.yaml \n \nAs well as projects, tasks and plugins data will be kept at $SPARROW_ROOT directory.\n\nFor example:\n\n    $ export SPARROW_ROOT=/opt/sparrow\n\n## SPARROW\\_NO\\_COLOR \n\nDisable color output.\n\n    $ export SPARROW_NO_COLOR=1\n\nAlso see \"Disable color output\" section.\n\n## SPARROW_CONF_PATH\n\nIf set defines an alternative location for sparrow configuration file.\n\n## sparrow_hub_api_url\n\n\nSets alternative location of SparrowHub API. If not set Sparrow client uses https://sparrowhub.org as API URL.\n\nPrimarily used  for internal testing and development. But also see [offline mode support](#offline-mode-support) section.\n\n## SPARROW_UNSECURE\n\nDisable ssl verification during `sparrow plg upload, sparrow remote task run` commands. Use this option on your risk.\n\n# Remote Tasks\n\n***WARNING!*** This feature is quite experimental and should be tested.\n\nRemote tasks are sparrow tasks SparrowHub users could _bind_ to theirs accounts:\n\n    $ sparrow project create utils\n\n    $ sparrow task add utils  git-setup git-base\n\n    $ sparrow task ini utils git-setup \n\n      email melezhik@gmail.com \n      name  'Alexey Melezhik'\n \n    $ sparrow task run utils git-setup\n\n\nOk, now we could \"wrap\" our task and upload to our account:\n\n    $ sparrow remote task upload utils/git-setup\n\n***NOTE!*** to upload remote task you need a SparrowHub account.\n\nThen I ssh-ing to another server to re-apply my git configuration:\n\n    $ ssh some-other-host\n    $ sparrow remote task install utils/git-setup\n\nNow I can:\n\n    $ sparrow task run utils git-setup\n\nPretty cool, huh? :)))\n\nA shortcut for `sparrow remote task install ... \u0026 sparrow task run` is:\n\n    $ sparrow remote task run utils/git-setup\n\n## Share your task\n\n_By default_ remote task uploaded to SparrowHub is only accessible by task author. This is so called\nprivate remote task. What if you want to share some fun stuff with people? - _Share_ your task:\n\n    $ sparrow remote task share utils/nano-rc\n\nNow users can use your remote task:\n\n    $ sparrow remote task install melezhik@utils/nano-rc\n    $ sparrow task run utils utils nano-rc\n\nor using shortcut in single step:\n\n    $ sparrow remote task run melezhik@utils/nano-rc\n\n***NOTE!*** you don't need a SparrowHub account to use public remote tasks, even unregisters users can use\npublic remote tasks.\n\n## Hide your task\n\nWant to hide your task again? Not a problem:\n\n    $ sparrow remote task hide app/passwords\n\nNow only you can use app/passwords task.\n\n## Add useful comments to task\n\nWhen doing remote task upload you optionally can add a comment which will be show \nwhen task gets listed with `sparrow remote task list` command:\n\n    $ sparrow remote task upload utils/nano-rc 'makes nano.rc setup'\n\n## List remote tasks\n\nTo list your remote tasks ( both private and public ) say this:\n\n    $ sparrow remote task list\n\n## List public tasks\n\nTo get a list of available public remote tasks say this:\n\n    $ sparrow remote task public list\n\n## Remove remote task\n\nAnd finally you can remove remote task:\n\n    $ sparrow remote task remove app/old-stuff\n\n# Offline mode support\n\n\nFor servers with limited or no access to internet, there is offline mode support.\n\n## Create local repository of Sparrow plugins\n\n\n    $ mkdir -p sparrow-local-repo/api/v1\n    $ mkidr -p sparrow-local-repo/plugins\n\n\n## Copy index file and plugins\n\n    $ curl https://sparrowhub.org/api/v1/index -o sparrow-local-repo/api/v1/index\n    $ curl https://sparrowhub.org/plugins/python-echo-script-v0.001000.tar.gz -o sparrow-local-repo/plugins/python-echo-script-v0.001000.tar.gz\n    $ # so on\n\n## Set sparrow\\_hub\\_api\\_url\n\n    $ export sparrow_hub_api_url=$PWD/sparrow-local-repo\n\nNow Sparrow client will be looking for local repository instead of making requests to internet.\n\n\n# AUTHOR\n\n[Aleksei Melezhik](mailto:melezhik@gmail.com)\n\n# Home page\n\n[https://github.com/melezhik/sparrow](https://github.com/melezhik/sparrow)\n\n# Copyright\n\nCopyright 2015 Alexey Melezhik.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.\n\n# See also\n\n* [SWAT](https://github.com/melezhik/swat) - Simple Web Application Test framework.\n\n* [Outthentic](https://github.com/melezhik/outthentic) - Multipurpose scenarios framework.\n\n# Thanks\n\nTo God as the One Who inspires me to do my job!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelezhik%2Fsparrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelezhik%2Fsparrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelezhik%2Fsparrow/lists"}