- Docs »
- Fabric
- Edit on GitHub
Please note
This documentation is for the latest stable (0.9.1) release of Fabric. To view documentation for the in-development (1.0) version, please click here.
To see the docs for the previous stable version, 0.9.0, please click here.
About¶
Fabric is a Python library and command-line tool for streamlining the use ofSSH for application deployment or systems administration tasks.
It provides a basic suite of operations for executing local or remote shellcommands (normally or via sudo) and uploading/downloading files, as well asauxiliary functionality such as prompting the running user for input, oraborting execution.
Typical use involves creating a Python module containing one or more functions,then executing them via the fab command-line tool. Below is a small butcomplete “fabfile” containing a single task:
from fabric.api import rundef host_type(): run('uname -s')
Once a task is defined, it may be run on one or more servers, like so:
$ fab -H localhost,linuxbox host_type[localhost] run: uname -s[localhost] out: Darwin[linuxbox] run: uname -s[linuxbox] out: LinuxDone.Disconnecting from localhost... done.Disconnecting from linuxbox... done.
In addition to use via the fab fool, Fabric’s components may be importedinto other Python code, providing a Pythonic interface to the SSH protocolsuite at a higher level than that provided by e.g. Paramiko (whichFabric itself leverages.)
Installation¶
Stable releases of Fabric are best installed via easy_install or pip;or you may download TGZ or ZIP source archives from a couple of officiallocations. Detailed instructions and links may be found on theInstallation page.
We recommend using the latest stable version of Fabric; releases are made oftento prevent any large gaps in functionality between the latest stable releaseand the development version.
However, if you want to live on the edge, you can pull down the latest sourcecode from our Git repository, or fork us on Github. The Installationpage has details for how to access the source code.
Development¶
Any hackers interested in improving Fabric (or even users interested in howFabric is put together or released) please see the Development page. Itcontains comprehensive info on contributing, repository layout, our releasestrategy, and more.
Documentation¶
Please note that all documentation is currently written with Python 2.5 usersin mind, but with an eye for eventual Python 3.x compatibility. This leads tothe following patterns that may throw off readers used to Python 2.4 or whohave already upgraded to Python 2.6:
- from __future__ import with_statement: a “future import” required touse the with statement in Python 2.5 – a feature you’ll be usingfrequently. Python 2.6 users don’t need to do this.
- <true_value> if <expression> else <false_value>: Python’s relatively newternary statement, available in 2.5 and newer. Python 2.4 and older used tofake this with <expression> and <true_value> or <false_value> (whichisn’t quite the same thing and has some logical loopholes.)
- print(<expression>) instead of print <expression>: We use theprint statement’s optional parentheses where possible, in order to bemore compatible with Python 3.x (in which print becomes a function.)
Tutorial¶
For new users, and/or for an overview of Fabric’s basic functionality, pleasesee the Overview and Tutorial. The rest of the documentation will assume you’reat least passingly familiar with the material contained within.
Usage documentation¶
The following list contains all major sections of Fabric’s prose (non-API)documentation, which expands upon the concepts outlined in theOverview and Tutorial and also covers advanced topics.
- The environment dictionary, env
- Execution model
- fab options and arguments
- Fabfile construction and use
- Managing output
- SSH behavior
FAQ¶
Some frequently encountered questions, coupled with answers/solutions/excuses,may be found on the Frequently Asked Questions (FAQ) page.
API documentation¶
Fabric maintains two sets of API documentation, autogenerated from the sourcecode’s docstrings (which are typically very thorough.)
Core API¶
The core API is loosely defined as those functions, classes and methodswhich form the basic building blocks of Fabric (such asrun and sudo) upon which everythingelse (the below “contrib” section, and user fabfiles) builds.
- Context Managers
- Decorators
- Operations
- Utils
Contrib API¶
Fabric’s contrib package contains commonly useful tools (often merged infrom user fabfiles) for tasks such as user I/O, modifying remote files, and soforth. While the core API is likely to remain small and relatively unchangedover time, this contrib section will grow and evolve (while trying to remainbackwards-compatible) as more use-cases are solved and added.
- Console Output Utilities
- File and Directory Management
- Project Tools
Changes from previous versions¶
- Changes in version 0.9
- Changes in version 0.9.1
Getting help¶
If you’ve scoured the prose and APIdocumentation and still can’t find an answer to your question, below arevarious support resources that should help. We do request that you do at leastskim the documentation before posting tickets or mailing list questions,however!
Mailing list¶
The best way to get help with using Fabric is via the fab-user mailing list (currently hosted atnongnu.org.) The Fabric developers do their best to reply promptly, and thelist contains an active community of other Fabric users and contributors aswell.
Bugs/ticket tracker¶
To file new bugs or search existing ones, you may visit Fabric’s Redmine instance, located at code.fabfile.org. Due to issues with spam, you’ll need to (quicklyand painlessly) register an account in order to post new tickets.
IRC¶
We maintain a semi-official IRC channel at #fabric on Freenode(irc://irc.freenode.net) where the developers and other users may be found.As always with IRC, we can’t promise immediate responses, but some folks keeplogs of the channel and will try to get back to you when they can.
Wiki¶
There is an official Fabric MoinMoin wiki reachable atwiki.fabfile.org, although as of this writing itsusage patterns are still being worked out. Like the ticket tracker, spam hasforced us to put anti-spam measures up: the wiki has a simple, easy captcha inplace on the edit form.
