PyPI - Version GitHub Actions Workflow Status PyPI - Python Version PyPI - License Static Badge

Welcome to FabricPlus’s documentation!

This site covers FabricPlus’s usage and API documentation.

It also serves as the main website for FabricPlus

If you are not familiar with Fabric, the first thing you should do is visit the main Fabric website.

If you are not familiar with the underlying behavior of Fabric, then you should read the Fabric documentation.

What is FabricPlus?

FabricPlus is a wrapper around several Fabric sourced objects to provide new functionality not currently a part of the main Fabric library. This includes:

  • ConnectionPlus object that wraps the Connection object from Fabric and extends it with:

    • Built-in support for jumphost (a.k.a. bastion) connectivity with MFA / 2FA support via paramiko-jump.

    • Built-in support for scp protocol transfer via the ssh connection, via scp.py.

    • Added support for su command execution via the Connection object for user switching, instead of needing to use sudo.

  • TransferPlus object that wraps the Transfer object from Fabric and extends it with:

    • Built-in support for scp protocol transfer via the ssh transport used by the parent Connection.

Quickstart

If you’re looking to get started quickly, here’s a brief set of examples for usage. Otherwise, read the “Getting Started” section below.

# importing as Connection
from fabricplus.connection import ConnectionPlus as Connection

# Creating a basic connection
conn_1: Connection = Connection("host1.example.com")

# Creating a jumphost connection, and then a host connection via that jumphost
jumphost_1: Connection = Connection("jumphost.example.com")
conn_via_jh: Connection = Connection("host2.example.com", jump_target=jumphost_1)

# Creating a host that uses SCP for transfers by default
conn_2: Connection("host3.example.com", scp=True)

# Running a get via SCP on the host1/conn_1, which doesn't use SCP by default
conn_1.get("/path/to/some/remote/file", scp=True)

# Running a command as some other user via su
conn_1.su("date", user="someotheruser", password="someuserspasswd")

Getting Started

Concurrency

If you’d like a little information on how to run Connections in parallel, here’s a small doc with some notes.

Contributing

Interested in contributing to FabricPlus? Great! We have a guide for that!

API

Just here to figure out how the API works?

API Documentation

Contact

If you need to get in touch about a bug, issue in the docs, or clarification, see the page below!