{
    "info": {
        "author": "Chris LaPointe",
        "author_email": "chris@zdyn.net",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# Unix System Monitoring Over SSH\n\nSshSysMon is a system/server monitoring tool that executes all of its operations over SSH without the\nneed for installing agents across machines.\n\nIts goal is to provide simple self-hosted monitoring and alerting for small numbers of lightweight\nservers without the traditional overhead of a monitoring system.\n\nIt monitors things in /proc and with simple command executions to monitor system vitals such as: memory, cpu load, drive space, swap, etc.\n\n\n\n\n\n## Setup\n\n### Installation\n\n#### Via PyPi\n\n```bash\npip install sshsysmon\n```\n\n#### Manually (No Install)\n\n```bash\n# Requires python 2.x and pip:\nsudo apt-get install -y python python-pip python-dev\n\n# Download the latest SshSysMon:\nwget -O - https://github.com/zix99/sshsysmon/archive/master.tar.gz | tar xzv\n\n# Make sure the dependencies are installed:\ncd sshsysmon-master/\nsudo pip install -r requirements.txt\n\n# Test it out!\n./sshmon summary examples/starter.yml\n```\n\n### Setting up a ssh key pair\n\n**You only need to do this if you are monitoring a remote server.**\n\nThe best way to connect to remote servers is with private key created and added to the `authorized_hosts` file on\nall systems you are interested in monitoring.  While password authentication is supported, this\nis the easiest way to guarantee continued authentication to other hosts.\n\nOn debian-based linux systems, setting up a key-pair to use with SSH is easy.  I would recommend\nyou make a new linux user to only do monitoring on each machine, but it isn't required.\n\n```bash\n# 1. Create a new SSH key if you don't already have one. Follow the prompts, but leave the password blank\nssh-keygen\n\n# 2. Install it on a user on another machine that you want to monitor\nssh-copy-id username@remotehost\n```\n\n\n### Running\n\nThe service has two commands, `summary` and `check`.\n\n#### Summary\n\n`summary` will print out a human-readable summary of all servers specified in the config. It is a\ngreat way to validate your config.\n\nIt can be executed with:\n\n    ./sshmon.py summary examples/starter.yml\n\nIt also can be told to use various templates. See templating section below. Eg, to use the html template:\n\n    ./sshmon.py -f html summary examples/starter.yml\n\n#### Check\n\n`check` is meant to be executed as part of a scheduled job, and will notify all channels in the config\nif a condition is unmet.\n\nIt can be excuted with:\n\n    ./sshmon.py check <myconfig.yml>\n\n\n### Running Scheduled Job\n\nThe best way to run the service automatically is with a cron job.\n\nEdit your cron jobs with\n\n    crontab -e\n\nAdd an entry that runs the script every few hours: (or minutes, whatever you like)\n\n    0 */4 * * * /path/to/sshmon.py check /path/to/config.yml\n\n\n### Configuration\n\nConfiguration is written in yaml and is a set of servers, with a list of monitors with alarms,\nnotification channels and connection details.\n\nSee the [Examples](/examples) folder for more sample configs.\n\nAn example simple configuration might look something like this:\n\n```\nmeta: #Meta section (Optional). Used by summary templates\n  title: \"My Cluster Summary\"\n  author: \"Me\"\n\nservers:\n  \"Name of server\":\n    driver: ssh\n    config:\n      host: myhostname.com\n      username: myuser\n    channels: # Notification targets\n      - type: email\n        config:\n          toAddr: myemail@gmail.com\n          subject: \"Something went wrong on {server}\"\n    monitors: # All alerts and inspectors\n      - type: memory\n        alarms:\n          \"Low Swap\": \"swap_free.mb < 50\"\n          \"Low Memory\": \"mem_free.mb < 5\"\n      - type: disk\n        alarms:\n          \"Low Disk Space\": \"disk_free.gb < 5\"\n        summarize: false # Optional, use if you don't want a monitor to show up in the summary\n```\n\nYou can often use YAML's inheritance to simplify your config for more than 1 server.  Each config section also\nhas a corresponding `+` version to add more in addition to something merged in.  eg. `monitors+`.\n\n\nAll servers are iterated through, and queried for given inspector types. The resulting `metrics` are compared to\nthe `alarms`, and if any of them are unmet, a notification it sent to all configured `channels`.\n\n#### Data Format\n\nAll sizes (that is, number of bytes), is enapsulated by the `ByteSize` class, which has helper methods for both friendly\noutput, and size casting in the form of `b`, `kb`, `mb`, etc.  eg, you can write `mem_free.mb > 50`.\n\nAll timedelta's are encapsulated by the `TimeSpan` class, which has properties that expose reduced forms.\nThey are `seconds`, `minutes`, `hours`, and `days`.\n\nPercentages will always be presented in their 0-100 form.\n\n---\n\n## Application\n\n### Components\n\nThe applications is built on three components: `Drivers`, `Inspectors`, and `Channels`.\n\nEach has its corresponding folder with abstract implementation.  They are loaded dynamically with their\nname or path provided in the configuration.\n\n#### Drivers\n\nDrivers are classes that define how to read information from a server.  By default, there are two drivers:\n\n##### Local\n\nThe local driver is only for your local machine. There is no config for this driver.\n\n##### SSH\n\nThe SSH driver is for reaching out to remote machines.  There are several config paramters for this driver:\n\n  * host - The hostname of the machine (IP or Domain)\n  * username - The username to connect with\n  * password - (Not recommended, use key instead) The ssh user's password\n  * key - The path to the private key to use to connect (Default: ~/.ssh/id_rsa)\n  * port - The port to connect to the machine on (Default: 22)\n  * path - The path which proc is located (Default: /proc)\n\n--\n\n#### Channels\n\nChannels define what can happen if an alert fires.  There a few built-in.\n\nThere are a few variables passed in that can be used to format part of the commands:\n\n  * server - The server that the alert triggered on\n  * alert - The alert that triggered (the name)\n  * inspector - The inspector that triggered the alert\n  * statement - The statement of the inspector that fired the alert\n\n##### stdout\n\nWrites tab-separated data to stdout.  Can be appended to file with bash `>>` operator.\n\nArguments:\n\n  * timeFormat - Either `ctime` or `epoch`, the format which time is output. Default: `ctime`\n  * format - The format string used to write output. Default: `{time}\\t{server}\\t{inspector}\\t{alert}`\n\n##### command\n\nExecutes a shell command on the machine in which the script is running.\n\nArguments:\n\n  * command - The shell command to execute\n\n##### email\n\nSends an email via a SMTP server.\n\nBy default, it assumes a local SMTP server is setup.  For more complex configs, such as how to use\ngmail, see the examples.\n\nArguments:\n\n  * toAddr - The address to send the email to\n  * fromAddr - The address the email should come from (default: username@hostname)\n  * host - The SMTP host (default: localhost)\n  * port - The SMTP port (default: 25)\n  * subject - Subject line of email (has reasonable default)\n  * username - Username to authenticate with smtp server (default: none)\n  * password - Password to authenticate with smtp server (default: none)\n  * tls - Should use tls (default: false)\n  * ssl - Should use ssl (default: false)\n\n##### webhook\n\nCalls an http/https endpoint and passes it the JSON model.\n\nArguments:\n\n * url - The URL to call\n * method - The method to use in the http request (default: POST)\n * headers - A dict of any additional headers to add to the request\n * verifySSL - Whether or not to verify SSL cert (default: True)\n\n--\n\n#### Inspectors (Alert Types)\n\nInspects are parsers that know how to read data from a driver and make sense of it.\n\n##### Memory (memory)\n\nThe memory driver returns metrics about the systems memory:\n\nMetrics: mem_total, mem_free, cached, swap_total, swap_free\n\n##### Disk Space (disk)\n\nThe Disk driver returns status of the disk space (in GB)\n\nConfig:\n\n  * device - The name of the device (Optional, eg /dev/sda)\n  * mount - The mount point of the device (default: /)\n\nMetrics: size, used, available, percent_full\n\n##### Load Average (loadavg)\n\nThe load average inspector returns the system's current 1/5/15 minute [load average](http://blog.scoutapp.com/articles/2009/07/31/understanding-load-averages).\n\nMetrics: load_1m, load_5m, load_15m\n\n##### Process Monitor (process)\n\nThis inspector will allow you monitor a process on the given machine.\n\nIt takes in one **required** config `name`. This will use [wildcard matching](https://docs.python.org/2/library/fnmatch.html) with `*` and `?`.\n\nMetrics: user, pid, cpu, mem, tty\n\n##### TCP (tcp)\n\nThe TCP inspector will try to establish a connection on a given port with the same\nremote as the driver.  It's important to note that this does **not** go over SSH, and will\nnot verify anything more than that the port is willing to establish a connection.\n\nConfig:\n\n  * ports: A list, single port, or CSV of ports to check\n\nMetrics:\n\n  * A dictionary of the requested ports, prefixed with `port_`, and true if they are open, otherwise false (eg `port_22`)\n  * A special `all` metric which will be true if all ports are open\n\n##### HTTP (http)\n\nThe Http connector will attempt to do a GET request on a http/https endpoint, and return the data if able.\n\nConfig:\n\n  * path: The path to request on (default '/')\n  * port: The port to request at (default 80 for http, 443 for https)\n  * https: True/false if https (default: http)\n  * json: true/false if it should attempt to parse the response as json (Default: false)\n  * match: A regex to match against (default: None)\n\nMetrics:\n\n  * success: A true/false whether the request returns a 2xx, and all requirements were met (matches, or parses)\n  * match: Whether or not the regex matched. `None` if no match requested\n  * json: The parsed json, if requested\n  * url: The requested url\n\n##### Custom Command (exec)\n\n`exec` runs a custom command and returns `stdout`, `stderr`, and `status` (returncode).\n\nConfig:\n\n  * command: The shell command to execute\n  * environment: Optional object of environment variables (Default: {})\n  * json: Try to parse the command's output as json (Default: false)\n  * extract: Dict of name:path pairs to extract as metrics, eg `a.[1].c` (Default: None) See: Extracting Typed Json below; json must be `true`\n\nProperties extracted as metrics can be used in alarms\n\nMetrics:\n\n**If json, those will be the output metrics instead**\n\n  * stdout: The out string of the command\n  * stderr: The err string of the command\n  * status: The returncode of the command (0 means normal)\n\n##### File/Path Metadata (FileMeta)\n\n`filemeta` gathers all the metadata of all files in a path\n\nConfig:\n\n  * path: Path to gather the file data\n  * match: Matcher to select files within path\n  * maxDepth: The max depth it searches for files\n  * minDepth: The min depth it searches for files\n\nMetrics:\n\n  * count: Number of files that match\n  * oldest: The TimeSpan object of the oldest file\n  * newest: The TimeSpan object of the newest file\n  * largest: ByteSize of the largest file\n  * smallest: ByteSize of smallest file\n  * files: Array of files\n    * path: Path to the file\n    * size: ByteSize of the file\n    * last_access: access date\n    * last_modified: last modified time\n    * age: TimeSpan since last modified\n\n##### Networking Metrics (network)\n\n`network` gathers information about the network usage of system interfaces.\n\nConfig:\n\n  * match: Wildcard match to interface name (Default: None)\n  * hideEmpty: Hide interfaces that are empty (no traffic) (Default: False)\n\nMetrics:\n\n  * totals\n    * received\n    * tranmitted\n  * interfaces\n\n##### Core System Metrics (system)\n\nMetrics:\n\n  * uptime: TimeSpan of the time up\n  * idle: CPU time that is idle\n\n### Data\n\n#### Extracting Typed Objects\n\nIn cases where SshSysMon can parse and explore json applications, you might want to interpret data\nin a certain way. For example, it may be useful to grab a nested property and compute the TimeSpan\nfrom now.\n\nObject path selections are separated by `.`, and the optional type follows a `:`\n\nFor example, if you have this object:\n```json\n{\n  \"a\" : {\n    \"b\" : [\n      \"2018-12-15T15:57:17.619242731+01:00\"\n    ]\n  }\n}\n```\n\nAnd you wanted to extract the number of time that has passed between that date and now, your\nselector would be `a.b.[0]:TimeSpanFromNow`\n\nThe following types are supported:\n\n  * str: Convert object to string\n  * int: Convert object to int\n  * TimeSpan: Assume object is int number-of-seconds, and make TimeSpan\n  * TimeSpanFromNow: Assume object is parseable datetime, and compute TimeSpan between then and now\n  * DateTime: Parse string as datetime\n\n### Templating\n\nSshSysMon uses handlebars to template its summary output.  See the [templating](/templates) for more information.\n\n### Writing Your Own Component\n\nTo learn how to write a specific type of component, visit its readme in the appropriate subfolder.\n\nAll components must define `def create(args):` as a well-known method to instantiate the class.  `args` will\nbe the configuration `dict` given in the configuration.\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/zix99/sshsysmon",
        "keywords": "monitoring,ssh,linux,unix",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "SshSysMon",
        "package_url": "https://pypi.org/project/SshSysMon/",
        "platform": "",
        "project_url": "https://pypi.org/project/SshSysMon/",
        "project_urls": {
            "Homepage": "https://github.com/zix99/sshsysmon"
        },
        "release_url": "https://pypi.org/project/SshSysMon/0.2.3/",
        "requires_dist": [
            "paramiko (==1.16.0)",
            "pyaml (==15.8.2)",
            "pybars3 (==0.9.1)"
        ],
        "requires_python": "",
        "summary": "Ssh Unix System Monitoring",
        "version": "0.2.3"
    },
    "last_serial": 5438801,
    "releases": {
        "0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7c67e96f2e8f2ef47c6c1a6cd6efad8e",
                    "sha256": "15cc4290733fda2f813d2bcb3f712276d88441cc051b21ce83d26323a1afe273"
                },
                "downloads": -1,
                "filename": "SshSysMon-0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "7c67e96f2e8f2ef47c6c1a6cd6efad8e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18089,
                "upload_time": "2016-05-08T01:03:09",
                "url": "https://files.pythonhosted.org/packages/32/fa/22369116b3aa05169c20c3969eb6d8cc20e45f9fd8efc2d98767004ed982/SshSysMon-0.2.tar.gz"
            }
        ],
        "0.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5fefb212311e675e059213134d249d4a",
                    "sha256": "ff35f80456bd75055dfe0e75110e8674fda584ac83bde6a6018adf2580ac13d5"
                },
                "downloads": -1,
                "filename": "SshSysMon-0.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "5fefb212311e675e059213134d249d4a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 47018,
                "upload_time": "2016-05-08T01:17:25",
                "url": "https://files.pythonhosted.org/packages/90/4f/2283301aed448f62f7e885adf7565f8fb191b91fd8c3d1f0e622080e2e37/SshSysMon-0.2.1.tar.gz"
            }
        ],
        "0.2.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "1c5165980404ee0ce4df83c2635b19a4",
                    "sha256": "6165d25dd9657f1d5ed04e236ea1b26d1613d5d92531d11290fd635094194b42"
                },
                "downloads": -1,
                "filename": "SshSysMon-0.2.3-py2-none-any.whl",
                "has_sig": false,
                "md5_digest": "1c5165980404ee0ce4df83c2635b19a4",
                "packagetype": "bdist_wheel",
                "python_version": "py2",
                "requires_python": null,
                "size": 35101,
                "upload_time": "2019-06-24T03:29:43",
                "url": "https://files.pythonhosted.org/packages/43/97/9170b0cbede152cd61374399985762f9ff861d04011667ba53d35adfa885/SshSysMon-0.2.3-py2-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "f36b85258ce0ecb62e1acfabf8a35fc0",
                    "sha256": "b7d488108bae674d6a13d0dd053d0a1a83373954e828b45068808f9bcd2146c4"
                },
                "downloads": -1,
                "filename": "SshSysMon-0.2.3.tar.gz",
                "has_sig": false,
                "md5_digest": "f36b85258ce0ecb62e1acfabf8a35fc0",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 29763,
                "upload_time": "2019-06-24T03:29:45",
                "url": "https://files.pythonhosted.org/packages/12/92/dcd614962f017d7d81b405e7cb18b07708318caabe5a69fccd58e0591bb4/SshSysMon-0.2.3.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "1c5165980404ee0ce4df83c2635b19a4",
                "sha256": "6165d25dd9657f1d5ed04e236ea1b26d1613d5d92531d11290fd635094194b42"
            },
            "downloads": -1,
            "filename": "SshSysMon-0.2.3-py2-none-any.whl",
            "has_sig": false,
            "md5_digest": "1c5165980404ee0ce4df83c2635b19a4",
            "packagetype": "bdist_wheel",
            "python_version": "py2",
            "requires_python": null,
            "size": 35101,
            "upload_time": "2019-06-24T03:29:43",
            "url": "https://files.pythonhosted.org/packages/43/97/9170b0cbede152cd61374399985762f9ff861d04011667ba53d35adfa885/SshSysMon-0.2.3-py2-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "f36b85258ce0ecb62e1acfabf8a35fc0",
                "sha256": "b7d488108bae674d6a13d0dd053d0a1a83373954e828b45068808f9bcd2146c4"
            },
            "downloads": -1,
            "filename": "SshSysMon-0.2.3.tar.gz",
            "has_sig": false,
            "md5_digest": "f36b85258ce0ecb62e1acfabf8a35fc0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 29763,
            "upload_time": "2019-06-24T03:29:45",
            "url": "https://files.pythonhosted.org/packages/12/92/dcd614962f017d7d81b405e7cb18b07708318caabe5a69fccd58e0591bb4/SshSysMon-0.2.3.tar.gz"
        }
    ]
}