Metadata-Version: 2.1
Name: pycons3rt
Version: 0.0.6
Summary: A python library for CONS3RT assets
Home-page: https://github.com/cons3rt/pycons3rt
Author: Joe Yennaco
Author-email: joe.yennaco@jackpinetech.com
License: GNU GPL v3
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: Operating System :: OS Independent
Requires-Dist: awscli
Requires-Dist: boto3
Requires-Dist: botocore
Requires-Dist: netifaces
Requires-Dist: jinja2
Requires-Dist: requests
Requires-Dist: requests[security]

# pycons3rt Python Library for CONS3RT Assets

## Features

* Gathers CONS3RT deployment info
* Runs Linux commands from python
* Configures networking on Linux
* Configuring AWS EC2 instance networking
* Downloads and uploads files to AWS S3
* Downloads files from a Nexus Artifact Repository
* Posts CONS3RT run info to Slack
* Establishes a logging infrastructure for python CONS3RT assets

## Installation

### Install from pip

If you have Python 2.7 installed, you can run:

`pip install pycons3rt`

Also you can install specific versions:

`pip install pycons3rt==0.0.2`

### Install from source

~~~
git clone https://github.com/cons3rt/pycons3rt
cd pycons3rt
python setup.py
~~~

### Install with CONS3RT assets

Search for community `pycons3rt` software assets in HmC or cons3rt.com to use.

To create your own pycons3rt assets, from the pycons3rt repo root directory, run:

    $ ./scripts/make-assets.sh

This will create your own Linux and Windows pycons3rt assets for import:

    ./build/asset-pycons3rt-linux.zip
    ./build/asset-pycons3rt-windows.zip

## Configuration

Once installed, run the following command to set up pycons3rt:

`pycons3rt_setup`

### Asset Prerequisites

1. Git
1. Python 2.7.x
1. pip

### Asset Exit Codes (Linux):

* 0 - Success
* Non-zero - See log file in /var/log/cons3rt/ for additional details

### Asset Exit Codes (Windows)

* 0 - Success
* 1 - Asset install failed:
  * pycons3rt install script not found, git clone may not have succeeded
  * There was a problem setting up pycons3rt
  * pycons3rt osutil not found
  * There was a problem running osutil


# pycons3rt documentation

## Configuration

When installed, pycons3rt creates a system directory (`pycons3rt_system_home`) and 
a local user directory (`pycons3rt_user_home`).  

The `pycons3rt_system_home` directory is located on your system here:

* Linux: `/etc/pycons3rt`
* MacOS: `~/.pycons3rt`
* Windows: `C:\pycons3rt`

The `pycons3rt_user_home` directory is here on all OS types:

* `~/.pycons3rt`

The following assets are also created:

* System pycons3rt config dir: `pycons3rt_system_home/conf/`
* User log dir (default): `pycons3rt_user_home/log/`
* Pycons3rt source dir: `pycons3rt_user_home/src/`

The asset clones the pycons3rt source code here for installation:

* `pycons3rt_user_home/src/pycons3rt`

The logging configuration file is installed here:

* `pycons3rt_system_home/conf/pycons3rt-logging.conf`

By default, pycons3rt log files will output here:

* `pycons3rt_user_home/log/pycons3rt-info.log`
* `pycons3rt_user_home/log/pycons3rt-warn.log`
* `pycons3rt_user_home/log/pycons3rt-debug.log`

## Logify

With the default configuration log files go to: `~/.pycons3rt/log/`, and INFO 
level is printed to stdout.  To customize pycons3rt logging, modify the 
`pycons3rt-logging.conf` file.

~~~
import logging
from pycons3rt.logify import Logify

mod_logger = Logify.get_name() + '.your_module'

    # Then use in a function or class:

    class MyClass(object):
        def __init__(self, dep=None):
            self.cls_logger = mod_logger + '.MyCLass'
    	def class_method(self):
    		log = logging.getLogger(self.cls_logger + '.class_method')
    		log.info('Class Method Logging')

    def main():
        log = logging.getLogger(mod_logger + '.main')
        log.debug('DEBUG')
    	log.info('INFO')
    	log.warn('WARN')
    	log.error('ERROR')
~~~

Deployment
---

This module provides a set of useful utilities for accessing CONS3RT
deployment related info. It is intended to be imported and used in
other python-based CONS3RT assets.

~~~
from pycons3rt.deployment import Deployment

# Create a new Deployment object
dep = new Deployment()

# Deployment name
print(dep.deployment_name)

# Get the role name
print(dep.cons3rt_role_name)

# Deployment properties
print(dep.properties)

# Get a specific deployment property value by name
my_value = dep.get_value('cons3rt.user')

# Scenario network info
print(dep.scenario_network_info)

# ASSET_DIR
print(dep.asset_dir)
~~~

Slack
---

This module provides an interface for posting anything to Slack!

~~~
from pycons3rt.slack import SlackMessage
from pycons3rt.slack import SlackAttachments

# Create a message
slack_msg = SlackMessage(
                my_webhook_url, 
                channel='#DevOps', 
                icon_url='http://cool-icon-url',
                text='This is a Slack message',
                user='@sender_username')

# Create and add an attachment
slack_attachment = SlackAttachment(
                       fallback='This is the fallback text', 
                       color='green', 
                       pretext='Pretext', 
                       text='Moar text!')

slack_msg.add_attachment(slack_attachment)

# Send a message
slack_msg.send()
~~~

## Nexus

This module provides simple method of fetching artifacts from a nexus
repository.

~~~
from pycons3rt import nexus

nexus.get_artifact(
    username=nexus_username,
    password=nexus_password,
    suppress_status=True,
    nexus_url=nexus_url,
    timeout_sec=45,
    overwrite=False,
    group_id='com.cons3rt',
    artifact_id='cons3rt-backend-install',
    version=`18.11.1`,
    packaging='zip',
    classifier='package-otto',
    destination_dir=dest_dir)
~~~

## Bash (Linux)

Executes commands on a Linux system.  See the source code for specific available
commands but the most commonly used `run_command` is shown below.

### run_command(command, timeout_sec=3600.0, output=True)

Parameters

* command: List containing the command and any additional args
* timeout_sec: (optional) Float specifying how long to wait before 
terminating the command.  Default is 3600.0.
* output: (boolean) True collects the output of the command.  In some cases
supressing the command output improves stability.

Returns:

* A dictionary containing "code", the numeric exit code from the command, and 
"output" which captures the stdout/strerrif output was set `True`. Sample output:

Raises: `CommandError` when there is a problem running the command.

~~~
{
    "code": "0",
    "output": "stdout/stderr from the command"
}
~~~

Example Usage:

~~~
from pycons3rt.bash import run_command
from pycons3rt.bash import CommandError
command = ['ls', '/root']
try:
    result = run_command(command, timeout_sec=60.0)
    code = result['code']
    output = result['output']
except CommandError:
    raise
if code == 0:
    log.info('Successfully executed command {c}'.format(s=command))
else:
    msg = 'There was a problem running command returned code {c} and produced output: {o}'.format(
                    c=code, o=output)
            log.error(msg)
            raise CommandError(msg)
~~~



## Alias IP (Linux)

Utility for setting IP address aliases in Linux.

## Cons3rtUtil

Utility for running CONS3RT CLI commands.  Only useful for CONS3RT site 
administrators with CLI access.

## OsUtil

Handles the initial pycons3rt configuration based on the detected OS type.

## PyGit

Utility for cloning a git repo from python.

## PyJavaKeys

Utility for importing Root Certificate Authority (CA) certificates into a 
Java keystore.

## Windows

Basic Windows utlities like adding host file entries.

