snap-cli

README

DISCONTINUATION OF PROJECT.

This project will no longer be maintained by Intel.

This project has been identified as having known security escapes.

Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.

Intel no longer accepts patches to this project.

snaptel

A Snap telemetry framework CLI

1. Getting Started
   • System Requirements
   • Operating systems
   • Installation
2. Documentation
   • Usage
   • Global Options
   • Commands
   • Command Options
   • Examples
3. Basic authentication
4. Secure Plugin Communication
5. Community Support
6. Contributing
7. License

Getting Started

System Requirements

• golang 1.7+ - needed only for building

Operating systems

All OSs currently supported by plugin:

• Linux/amd64

Installation

You can get the pre-built snaptel binary for your OS and architecture at Snap CLI's GitHub Releases page.

To build the snap cli:

Fork https://github.com/intelsdi-x/snap-cli Clone repo into $GOPATH/src/github.com/intelsdi-x/:

$ git clone https://github.com/<yourGithubID>/snap-cli.git

Build the plugin by running make within the cloned repo:

$ make

This builds the snaptel in /build/$GOOS/$GOARCH

Documentation

Usage

Either copy snaptel to /usr/local/sbin and ensure /usr/local/sbin is in your path, or use fully qualified filepath to the snaptel binary:

$ snaptel [global options] command [command options] [arguments...]

Global Options

--url value, -u value          Sets the URL to use (default: "http://localhost:8181") [$SNAP_URL]
--insecure                     Ignore certificate errors when Snap API is running HTTPS [$SNAP_INSECURE]
--api-version value, -a value  The Snap API version (default: "v2") [$SNAP_API_VERSION]
--password, -p                 Require password for REST API authentication [$SNAP_REST_PASSWORD]
--config value, -c value       Path to a config file [$SNAPTEL_CONFIG_PATH, $SNAPCTL_CONFIG_PATH]
--timeout value, -t value      Timeout to be set on HTTP request to the server (default: 10s)
--help, -h                     show help
--version, -v                  print the version

Commands

metric
plugin
task
help, h      Shows a list of commands or help for one command

Command Options

plugin

$ snaptel plugin command [command options] [arguments...]

load    load <plugin_path> [--plugin-cert=<plugin_cert_path> --plugin-key=<plugin_key_path> --plugin-ca-certs=<ca_cert_paths>]
unload  unload <plugin_type> <plugin_name> <plugin_version>
list    list or list --running
config

metric

$ snaptel metric command [command options] [arguments...]

list  list
get   get -m <namespace> or get -m <namespace> -v <version>

task

$ snaptel task command [command options] [arguments...]

create  There are two ways to create a task.
        1) Use a task manifest with [--task-manifest]
        2) Provide a workflow manifest and schedule details.


       --task-manifest value, -t value      File path for task manifest to use for task creation.
       --workflow-manifest value, -w value  File path for workflow manifest to use for task creation
       --interval value, -i value           Interval for the task schedule [ex (simple schedule): 250ms, 1s, 30m (cron schedule): "0 * * * * *"]
       --count value                        The count of runs for the task schedule [defaults to 0 what means no limit, e.g. set to 1 determines a single run task]
       --start-date value                   Start date for the task schedule [defaults to today]
       --start-time value                   Start time for the task schedule [defaults to now]
       --stop-date value                    Stop date for the task schedule [defaults to today]
       --stop-time value                    Start time for the task schedule [defaults to now]
       --name value, -n value               Optional requirement for giving task names
       --duration value, -d value           The amount of time to run the task [appends to start or creates a start time before a stop]
       --no-start                           Do not start task on creation [normally started on creation]
       --deadline value                     The deadline for the task to be killed after started if the task runs too long (All tasks default to 5s)
       --max-failures value                 The number of consecutive failures before Snap disables the task

        * Note: Start and stop date/time are optional.

list    list or list --verbose
start   start <task_id>
stop    stop <task_id>
remove  remove <task_id>
export  export <task_id>
watch   watch <task_id> or watch <task_id> --verbose
enable  enable <task_id>

Examples

Load and unload plugins, create and start a task

In one terminal window, run snapteld (log level is set to 1 and signing is turned off for this example):

$ snapteld --log-level 1 --log-path '' --plugin-trust 0

prepare a task manifest file, for example, task.json with following content:

{
    "version": 1,
    "name": "sample",
    "schedule": {
        "type": "simple",
        "interval": "15s"
    },
    "workflow": {
        "collect": {
            "metrics": {
                "/intel/mock/foo": {},
                "/intel/mock/bar": {},
                "/intel/mock/*/baz": {}
            },
            "config": {
                "/intel/mock": {
                    "user": "root",
                    "password": "secret"
                }
            },
            "process": null,
            "publish": [
                {
                    "plugin_name": "file",                            
                    "config": {
                        "file": "/tmp/collected_swagger"
                    }
                }
            ]             
        }
    }
}

prepare a workflow manifest file, for example, workflow.json with the following content:

{
    "collect": {
        "metrics": {
            "/intel/mock/foo": {}
        },
        "config": {
            "/intel/mock/foo": {
                "password": "testval"
            }
        },
        "process": [],
        "publish": [
            {
                "plugin_name": "file",
                "config": {
                    "file": "/tmp/rest.test"
                }
            }
        ]
    }
}

and then in another terminal:

1. load a collector plugin
2. load a processing plugin
3. load a publishing plugin
4. list the plugins
5. list running plugins
6. swap plugins
7. list loaded metrics
8. list loaded metrics with details
9. list a specific metric including all versions
10. list a specific metric with its version
11. list a plugin config
12. unload the plugins
13. create a task using task manifest
14. create a task using workflow
15. create a single run task
16. list tasks
17. watch a task
18. export a task
19. stop a task

$ snaptel plugin load /opt/snap/plugins/snap-plugin-collector-mock1
$ snaptel plugin load /opt/snap/plugins/snap-plugin-processor-passthru
$ snaptel plugin load /opt/snap/plugins/snap-plugin-publisher-mock-file
$ snaptel plugin list
$ snaptel plugin list --running
$ snaptel metric list
$ snaptel metric list --verbose
$ snaptel metric get -m /intel/mock/foo
$ snaptel metric get -m /intel/mock/foo -v <version>
$ snaptel plugin config get <plugin_type>:<plugin_name>:<plugin_version>
$ snaptel plugin config get -t <plugin_type> -n <plugin_name> -v <plugin_version>
$ snaptel plugin unload collector <plugin_name> <plugin_version>
$ snaptel task create -t mock-file.json
$ snaptel task create -w workflow.json -i 1s
$ snaptel task create -t mock-file.yml --count 1
$ snaptel task list
$ snaptel task watch <task_id>
$ snaptel task export <task_id>
$ snaptel task stop <task_id>

Basic Authentication

Basic authentication is an optional authentication handler for Snap CLI.

Referring to docs/BASIC_AUTHENTICATION.md for details.

Secure Plugin Communication

Snap framework communicates with plugins (collectors, processors and publishers) over gRPC protocol. This communication can be secured by opening TLS channels and providing certificates to authenticate both sides: plugins and Snap daemon.

Snap CLI exposes the following flags to allow loading the plugin together with paths to its key and certificate files which are required to setup TLS communication:

$ snaptel plugin load --help

USAGE:
   snaptel plugin load [command options] [arguments...]

OPTIONS:
   --plugin-asc value, -a value       The plugin asc
   --plugin-cert value, -c value      The path to plugin certificate file
   --plugin-key value, -k value       The path to plugin private key file
   --plugin-ca-certs value, -r value  List of CA cert paths (directory/file) for plugin to verify TLS clients

Referring to docs/TLS_SECURE_PLUGIN_COMMUNICATION.md for details.

Community Support

This repository is one of many in the Snap framework and has maintainers supporting it. We love contributions from our community along the way. No improvement is too small.

Contributing

We encourage contributions from the community.

• Contributors: We always appreciate more eyes on the core framework and Snap CLIs
• Feedback: try it and tell us about it on our Slack team or through a blog posts
• Integrations: snap-cli uses snap-client-go

To contribute to the Snap framework, see our CONTRIBUTING.md file. To give back to a specific plugin, open an issue on its repository. Snap maintainers aim to address comments and questions as quickly as possible. To get some attention on an issue, reach out to us on Slack, or open an issue to get a conversation started.

Code of Conduct

All contributors to snap-cli are expected to be helpful and encouraging to all members of the community, treating everyone with a high level of professionalism and respect. See our code of conduct for more details.

License

Snap CLI is an Open Source software released under the Apache 2.0 License.

Thank You

And thank you! Your contribution, through code and participation, is incredibly important to us.