Welcome to fabtools’s documentation!¶

Apache¶

This module provides tools for configuring the Apache HTTP Server.

fabtools.apache.is_module_enabled(module)[source]¶

Check if an Apache module is enabled.

fabtools.apache.enable_module(module)[source]¶

Enable an Apache module.

This creates a symbolic link from /etc/apache2/mods-available/ into /etc/apache2/mods-enabled/.

This does not cause Apache to reload its configuration.

import fabtools

fabtools.apache.enable_module('rewrite')
fabtools.service.reload('apache2')

See also

fabtools.require.apache.module_enabled()

fabtools.apache.disable_module(module)[source]¶

Disable an Apache module.

This deletes the symbolink link in /etc/apache2/mods-enabled/.

This does not cause Apache to reload its configuration.

import fabtools

fabtools.apache.disable_module('rewrite')
fabtools.service.reload('apache2')

See also

fabtools.require.apache.module_disabled()

fabtools.apache.is_site_enabled(site_name)[source]¶

Check if an Apache site is enabled.

fabtools.apache.enable_site(site_name)[source]¶

Enable an Apache site.

This creates a symbolic link from /etc/apache2/sites-available/ into /etc/apache2/sites-enabled/.

This does not cause Apache to reload its configuration.

import fabtools

fabtools.apache.enable_site('default')
fabtools.service.reload('apache2')

See also

fabtools.require.apache.site_enabled()

fabtools.apache.disable_site(site_name)[source]¶

Disable an Apache site.

This deletes the symbolink link in /etc/apache2/sites-enabled/.

This does not cause Apache to reload its configuration.

import fabtools

fabtools.apache.disable_site('default')
fabtools.service.reload('apache2')

See also

fabtools.require.apache.site_disabled()

Arch Linux packages¶

This module provides tools to manage Arch Linux packages and repositories.

fabtools.arch.update_index(quiet=True)[source]¶

Update pacman package definitions.

fabtools.arch.upgrade()[source]¶

Upgrade all packages.

fabtools.arch.is_installed(pkg_name)[source]¶

Check if an Arch Linux package is installed.

fabtools.arch.install(packages, update=False, options=None)[source]¶

Install one or more Arch Linux packages.

If update is True, the package definitions will be updated first, using update_index().

Extra options may be passed to pacman if necessary.

Example:

import fabtools

# Update index, then install a single package
fabtools.arch.install('mongodb', update=True)

# Install multiple packages
fabtools.arch.install([
    'mongodb',
    'python-pymongo',
])

fabtools.arch.uninstall(packages, options=None)[source]¶

Remove one or more Arch Linux packages.

Extra options may be passed to pacman if necessary.

Cron tasks¶

This module provides tools to manage periodic tasks using cron.

fabtools.cron.add_task(name, timespec, user, command, environment=None)[source]¶

Add a cron task.

The command will be run as user periodically.

You can use any valid crontab(5) timespec, including the @hourly, @daily, @weekly, @monthly and @yearly shortcuts.

You can also provide an optional dictionary of environment variables that should be set when running the periodic command.

Examples:

from fabtools.cron import add_task

# Run every month
add_task('cleanup', '@monthly', 'alice', '/home/alice/bin/cleanup.sh')

# Run every tuesday and friday at 5:30am
add_task('reindex', '30 5 * * 2,4', 'bob', '/home/bob/bin/reindex.sh')

fabtools.cron.add_daily(name, user, command, environment=None)[source]¶

Shortcut to add a daily cron task.

Example:

import fabtools

# Run every day
fabtools.cron.add_daily('backup', 'root', '/usr/local/bin/backup.sh')

Debian packages¶

This module provides tools to manage Debian/Ubuntu packages and repositories.

fabtools.deb.update_index(quiet=True)[source]¶

Update APT package definitions.

fabtools.deb.upgrade(safe=True)[source]¶

Upgrade all packages.

fabtools.deb.is_installed(pkg_name)[source]¶

Check if a package is installed.

fabtools.deb.install(packages, update=False, options=None, version=None)[source]¶

Install one or more packages.

If update is True, the package definitions will be updated first, using update_index().

Extra options may be passed to apt-get if necessary.

Example:

import fabtools

# Update index, then install a single package
fabtools.deb.install('build-essential', update=True)

# Install multiple packages
fabtools.deb.install([
    'python-dev',
    'libxml2-dev',
])

# Install a specific version
fabtools.deb.install('emacs', version='23.3+1-1ubuntu9')

fabtools.deb.uninstall(packages, purge=False, options=None)[source]¶

Remove one or more packages.

If purge is True, the package configuration files will be removed from the system.

Extra options may be passed to apt-get if necessary.

fabtools.deb.preseed_package(pkg_name, preseed)[source]¶

Enable unattended package installation by preseeding debconf parameters.

Example:

import fabtools

# Unattended install of Postfix mail server
fabtools.deb.preseed_package('postfix', {
    'postfix/main_mailer_type': ('select', 'Internet Site'),
    'postfix/mailname': ('string', 'example.com'),
    'postfix/destinations': ('string', 'example.com, localhost.localdomain, localhost'),
})
fabtools.deb.install('postfix')

fabtools.deb.get_selections()[source]¶

Get the state of dkpg selections.

Returns a dict with state => [packages].

fabtools.deb.apt_key_exists(keyid)[source]¶

Check if the given key id exists in apt keyring.

fabtools.deb.add_apt_key(filename=None, url=None, keyid=None, keyserver='subkeys.pgp.net', update=False)[source]¶

Trust packages signed with this public key.

Example:

import fabtools

# Varnish signing key from URL and verify fingerprint)
fabtools.deb.add_apt_key(keyid='C4DEFFEB', url='http://repo.varnish-cache.org/debian/GPG-key.txt')

# Nginx signing key from default key server (subkeys.pgp.net)
fabtools.deb.add_apt_key(keyid='7BD9BF62')

# From custom key server
fabtools.deb.add_apt_key(keyid='7BD9BF62', keyserver='keyserver.ubuntu.com')

# From a file
fabtools.deb.add_apt_key(keyid='7BD9BF62', filename='nginx.asc'

fabtools.deb.last_update_time()[source]¶

Get the time of last APT index update

This is the last modification time of /var/lib/apt/periodic/fabtools-update-success-stamp.

Returns -1 if there was no update before.

Example:

import fabtools

print(fabtools.deb.last_update_time())
# 1377603808.02

Disk Tools¶

fabtools.disk.partitions(device='')[source]¶

Get a partition list for all disk or for selected device only

Example:

from fabtools.disk import partitions

spart = {'Linux': 0x83, 'Swap': 0x82}
parts = partitions()
# parts =  {'/dev/sda1': 131, '/dev/sda2': 130, '/dev/sda3': 131}
r = parts['/dev/sda1'] == spart['Linux']
r = r and parts['/dev/sda2'] == spart['Swap']
if r:
    print("You can format these partitions")

fabtools.disk.getdevice_by_uuid(uuid)[source]¶

Get a HDD device by uuid

Example:

from fabtools.disk import getdevice_by_uuid

device = getdevice_by_uuid("356fafdc-21d5-408e-a3e9-2b3f32cb2a8c")
if device:
    mount(device,'/mountpoint')

fabtools.disk.mount(device, mountpoint)[source]¶

Mount a partition

Example:

from fabtools.disk import mount

mount('/dev/sdb1', '/mnt/usb_drive')

fabtools.disk.swapon(device)[source]¶

Active swap partition

Example:

from fabtools.disk import swapon

swapon('/dev/sda1')

fabtools.disk.ismounted(device)[source]¶

Check if partition is mounted

Example:

from fabtools.disk import ismounted

if ismounted('/dev/sda1'):
   print ("disk sda1 is mounted")

fabtools.disk.mkfs(device, ftype)[source]¶

Format filesystem

Example:

from fabtools.disk import mkfs

mkfs('/dev/sda2', 'ext4')

fabtools.disk.mkswap(device)[source]¶

Format swap partition

Example:

from fabtools.disk import mkswap

mkswap('/dev/sda2')

Files and directories¶

fabtools.files.is_file(path, use_sudo=False)[source]¶

Check if a path exists, and is a file.

fabtools.files.is_dir(path, use_sudo=False)[source]¶

Check if a path exists, and is a directory.

fabtools.files.is_link(path, use_sudo=False)[source]¶

Check if a path exists, and is a symbolic link.

fabtools.files.owner(path, use_sudo=False)[source]¶

Get the owner name of a file or directory.

fabtools.files.group(path, use_sudo=False)[source]¶

Get the group name of a file or directory.

fabtools.files.mode(path, use_sudo=False)[source]¶

Get the mode (permissions) of a file or directory.

Returns a string such as '0755', representing permissions as an octal number.

fabtools.files.umask(use_sudo=False)[source]¶

Get the user’s umask.

Returns a string such as '0002', representing the user’s umask as an octal number.

If use_sudo is True, this function returns root’s umask.

fabtools.files.upload_template(filename, destination, context=None, use_jinja=False, template_dir=None, use_sudo=False, backup=True, mirror_local_mode=False, mode=None, mkdir=False, chown=False, user=None)[source]¶

Upload a template file.

This is a wrapper around fabric.contrib.files.upload_template() that adds some extra parameters.

If mkdir is True, then the remote directory will be created, as the current user or as user if specified.

If chown is True, then it will ensure that the current user (or user if specified) is the owner of the remote file.

fabtools.files.md5sum(filename, use_sudo=False)[source]¶

Compute the MD5 sum of a file.

class fabtools.files.watch(filenames, callback=None, use_sudo=False)[source]¶

Context manager to watch for changes to the contents of some files.

The filenames argument can be either a string (single filename) or a list (multiple filenames).

You can read the changed attribute at the end of the block to check if the contents of any of the watched files has changed.

You can also provide a callback that will be called at the end of the block if the contents of any of the watched files has changed.

Example using an explicit check:

from fabric.contrib.files import comment, uncomment

from fabtools.files import watch
from fabtools.services import restart

# Edit configuration file
with watch('/etc/daemon.conf') as config:
    uncomment('/etc/daemon.conf', 'someoption')
    comment('/etc/daemon.conf', 'otheroption')

# Restart daemon if needed
if config.changed:
    restart('daemon')

Same example using a callback:

from functools import partial

from fabric.contrib.files import comment, uncomment

from fabtools.files import watch
from fabtools.services import restart

with watch('/etc/daemon.conf', callback=partial(restart, 'daemon')):
    uncomment('/etc/daemon.conf', 'someoption')
    comment('/etc/daemon.conf', 'otheroption')

fabtools.files.uncommented_lines(filename, use_sudo=False)[source]¶

Get the lines of a remote file, ignoring empty or commented ones

fabtools.files.getmtime(path, use_sudo=False)[source]¶

Return the time of last modification of path. The return value is a number giving the number of seconds since the epoch

Same as os.path.getmtime()

fabtools.files.copy(source, destination, recursive=False, use_sudo=False)[source]¶

Copy a file or directory

fabtools.files.move(source, destination, use_sudo=False)[source]¶

Move a file or directory

fabtools.files.symlink(source, destination, use_sudo=False)[source]¶

Create a symbolic link to a file or directory

fabtools.files.remove(path, recursive=False, use_sudo=False)[source]¶

Remove a file or directory

Git¶

This module provides low-level tools for managing Git repositories. You should normally not use them directly but rather use the high-level wrapper fabtools.require.git.working_copy() instead.

fabtools.git.clone(remote_url, path=None, use_sudo=False, user=None)[source]¶

Clone a remote Git repository into a new directory.

Parameters:	remote_url (str) – URL of the remote repository to clone. path (str) – Path of the working copy directory. Must not exist yet. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

fabtools.git.add_remote(path, name, remote_url, use_sudo=False, user=None, fetch=True)[source]¶

Add a remote Git repository into a directory.

Parameters:

path (str) – Path of the working copy directory. This directory must exist and be a Git working copy with a default remote to fetch from. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect. name (str) – name for the remote repository remote_url (str) – URL of the remote repository fetch (bool) – If True execute git remote add -f

fabtools.git.fetch(path, use_sudo=False, user=None, remote=None)[source]¶

Fetch changes from the default remote repository.

This will fetch new changesets, but will not update the contents of the working tree unless yo do a merge or rebase.

Parameters:	path (str) – Path of the working copy directory. This directory must exist and be a Git working copy with a default remote to fetch from. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

fabtools.git.pull(path, use_sudo=False, user=None, force=False)[source]¶

Fetch changes from the default remote repository and merge them.

Parameters:

path (str) – Path of the working copy directory. This directory must exist and be a Git working copy with a default remote to pull from. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect. force (bool) – If True, append the --force option to the command.

fabtools.git.checkout(path, branch='master', use_sudo=False, user=None, force=False)[source]¶

Checkout a branch to the working directory.

Parameters:

path (str) – Path of the working copy directory. This directory must exist and be a Git working copy. branch (str) – Name of the branch to checkout. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect. force (bool) – If True, append the --force option to the command.

GVM¶

This module provides tools for installing GVM : the Groovy enVironment Manager

fabtools.gvm.install(java_version=None)[source]¶

Install dependencies (curl and unzip) and Install GVM

import fabtools

# Install GVM
fabtools.gvm.install()

fabtools.gvm.install_candidate(candidate, version=None, java_version=None)[source]¶

Install a candidate

import fabtools

# Install a GVM candidate (For example Groovy)
fabtools.gvm.install_candidate('groovy')

Groups¶

fabtools.group.exists(name)[source]¶

Check if a group exists.

fabtools.group.create(name, gid=None)[source]¶

Create a new group.

Example:

import fabtools

if not fabtools.group.exists('admin'):
    fabtools.group.create('admin')

Mercurial¶

This module provides low-level tools for managing Mercurial repositories. You should normally not use them directly but rather use the high-level wrapper fabtools.require.mercurial.working_copy() instead.

fabtools.mercurial.clone(remote_url, path=None, use_sudo=False, user=None)[source]¶

Clone a remote Mercurial repository into a new directory.

Parameters:	remote_url (str) – URL of the remote repository to clone. path (str) – Path of the working copy directory. Must not exist yet. use_sudo (bool) – If True execute hg with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

fabtools.mercurial.update(path, branch='default', use_sudo=False, user=None, force=False)[source]¶

Merge changes to a working copy and/or switch branches.

Parameters:	path (str) – Path of the working copy directory. This directory must exist and be a Mercurial working copy. use_sudo (bool) – If True execute hg with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

fabtools.mercurial.pull(path, use_sudo=False, user=None)[source]¶

Pull changes from the default remote repository.

Parameters:	path (str) – Path of the working copy directory. This directory must exist and be a Mercurial working copy with a default remote to pull from. use_sudo (bool) – If True execute hg with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

MySQL users and databases¶

This module provides tools for creating MySQL users and databases.

Network¶

fabtools.network.interfaces()[source]¶

Get the list of network interfaces. Will return all datalinks on SmartOS.

fabtools.network.address(interface)[source]¶

Get the IPv4 address assigned to an interface.

Example:

import fabtools

# Print all configured IP addresses
for interface in fabtools.network.interfaces():
    print(fabtools.network.address(interface))

fabtools.network.nameservers()[source]¶

Get the list of nameserver addresses.

Example:

import fabtools

# Check that all name servers are reachable
for ip in fabtools.network.nameservers():
    run('ping -c1 %s' % ip)

Nginx¶

This module provides tools for managing the Nginx web server.

fabtools.nginx.enable(config)[source]¶

Create link from /etc/nginx/sites-available/ in /etc/nginx/sites-enabled/

(does not reload nginx config)

::

from fabtools import require

require.nginx.enable(‘default’)

See also

fabtools.require.nginx.enabled()

fabtools.nginx.disable(config)[source]¶

Delete link in /etc/nginx/sites-enabled/

(does not reload nginx config)

::

from fabtools import require

require.nginx.disable(‘default’)

See also

fabtools.require.nginx.disabled()

Node.js¶

This module provides tools for installing Node.js and managing packages using npm.

fabtools.nodejs.install_from_source(version='0.10.13', checkinstall=False)[source]¶

Install Node JS from source.

If checkinstall is True, a distribution package will be built.

import fabtools

# Install Node.js
fabtools.nodejs.install_nodejs()

Note

This function may not work for old versions of Node.js.

fabtools.nodejs.version(node='node')[source]¶

Get the version of Node.js currently installed.

Returns None if it is not installed.

fabtools.nodejs.install_package(package, version=None, local=False, npm='npm')[source]¶

Install a Node.js package.

If local is True, the package will be installed locally.

import fabtools

# Install package globally
fabtools.nodejs.install_package('express')

# Install package locally
fabtools.nodejs.install_package('underscore', local=False)

fabtools.nodejs.install_dependencies(npm='npm')[source]¶

Install Node.js package dependencies.

This function calls npm install, which will locally install all packages specified as dependencies in the package.json file found in the current directory.

from fabric.api import cd
from fabtools import nodejs

with cd('/path/to/nodejsapp/'):
    nodejs.install_dependencies()

fabtools.nodejs.package_version(package, local=False, npm='npm')[source]¶

Get the installed version of a Node.js package.

Returns None``is the package is not installed. If *local* is ``True, returns the version of the locally installed package.

fabtools.nodejs.update_package(package, local=False, npm='npm')[source]¶

Update a Node.js package.

If local is True, the package will be updated locally.

fabtools.nodejs.uninstall_package(package, version=None, local=False, npm='npm')[source]¶

Uninstall a Node.js package.

If local is True, the package will be uninstalled locally.

import fabtools

# Uninstall package globally
fabtools.nodejs.uninstall_package('express')

# Uninstall package locally
fabtools.nodejs.uninstall_package('underscore', local=False)

OpenVZ containers¶

This module provides high-level tools for managing OpenVZ templates and containers.

opkg packages¶

This module provides tools to manage opkg packages and repositories.

fabtools.opkg.update_index(quiet=True)[source]¶

Update opkg package definitions.

fabtools.opkg.upgrade()[source]¶

Upgrade all packages.

fabtools.opkg.is_installed(pkg_name)[source]¶

Check if a package is installed.

fabtools.opkg.install(packages, update=False, options=None)[source]¶

Install one or more packages.

If update is True, the package definitions will be updated first, using update_index().

Extra options may be passed to opkg if necessary.

Example:

import fabtools

# Update index, then install a single package
fabtools.opkg.install('build-essential', update=True)

# Install multiple packages
fabtools.opkg.install([
    'mc',
    'htop',
])

fabtools.opkg.uninstall(packages, options=None)[source]¶

Remove one or more packages.

Extra options may be passed to opkg if necessary.

Oracle JDK¶

This module provides tools for installing Oracle JDK

fabtools.oracle_jdk.install_from_oracle_site(version='7u25-b15')[source]¶

Download tarball from Oracle site and install JDK.

import fabtools

# Install Oracle JDK
fabtools.oracle_jdk.install_from_oracle_site()

fabtools.oracle_jdk.version()[source]¶

Get the version of currently installed JDK.

Returns None if it is not installed.

SmartOS packages¶

This module provides tools to manage SmartOS packages.

fabtools.pkg.update_index(force=False)[source]¶

Update pkgin package definitions.

fabtools.pkg.upgrade(full=False)[source]¶

Upgrade all packages.

fabtools.pkg.is_installed(pkg_name)[source]¶

Check if a package is installed.

fabtools.pkg.install(packages, update=False, yes=None, options=None)[source]¶

Install one or more packages.

If update is True, the package definitions will be updated first, using update_index().

Extra yes may be passed to pkgin to validate license if necessary.

Extra options may be passed to pkgin if necessary.

Example:

import fabtools

# Update index, then verbosely install a single package
fabtools.pkg.install('redis', update=True, options='-V',)

# Install multiple packages
fabtools.pkg.install([
    'unzip',
    'top'
])

fabtools.pkg.uninstall(packages, orphan=False, options=None)[source]¶

Remove one or more packages.

If orphan is True, orphan dependencies will be removed from the system.

Extra options may be passed to pkgin if necessary.

fabtools.pkg.smartos_build()[source]¶

Get the build of SmartOS. Useful to determine provider for example.

Example:

from fabtools.pkg import smartos_build

if smartos_build().startswith('joyent'):
    print('SmartOS Joyent')

fabtools.pkg.smartos_image()[source]¶

Get the SmartOS image. Useful to determine the image/dataset for example. Returns None if it can’t be determined.

Example:

from fabtools.pkg import smartos_image

if smartos_image().startswith('percona'):
    sudo("mysql -uroot -psecretpassword -e 'show databases;'")

Gentoo packages¶

This module provides tools for managing Gentoo packages and repositories using the Portage package manager.

fabtools.portage.update_index(quiet=True)[source]¶

Update Portage package definitions.

fabtools.portage.is_installed(pkg_name)[source]¶

Check if a Portage package is installed.

fabtools.portage.install(packages, update=False, options=None)[source]¶

Install one or more Portage packages.

If update is True, the package definitions will be updated first, using update_index().

Extra options may be passed to emerge if necessary.

Example:

import fabtools

# Update index, then install a single package
fabtools.portage.install('mongodb', update=True)

# Install multiple packages
fabtools.arch.install([
    'dev-db/mongodb',
    'pymongo',
])

fabtools.portage.uninstall(packages, options=None)[source]¶

Remove one or more Portage packages.

Extra options may be passed to emerge if necessary.

PostgreSQL users and databases¶

This module provides tools for creating PostgreSQL users and databases.

Python environments and packages¶

This module provides tools for using Python virtual environments and installing Python packages using the pip installer.

Python packages¶

This module provides tools for installing Python packages using the easy_install command provided by setuptools.

fabtools.python_setuptools.package_version(name, python_cmd='python')[source]¶

Get the installed version of a package

Returns None if it can’t be found.

fabtools.python_setuptools.is_setuptools_installed(python_cmd='python')[source]¶

Check if setuptools is installed.

fabtools.python_setuptools.install_setuptools(python_cmd='python', use_sudo=True)[source]¶

Install the latest version of setuptools.

import fabtools

fabtools.python_setuptools.install_setuptools()

fabtools.python_setuptools.install(packages, upgrade=False, use_sudo=False, python_cmd='python')[source]¶

Install Python packages with easy_install.

Examples:

import fabtools

# Install a single package
fabtools.python_setuptools.install('package', use_sudo=True)

# Install a list of packages
fabtools.python_setuptools.install(['pkg1', 'pkg2'], use_sudo=True)

Note

most of the time, you’ll want to use fabtools.python.install() instead, which uses pip to install packages.

RPM packages¶

This module provides tools to manage CentOS/RHEL/SL/Fedora packages and repositories.

fabtools.rpm.update(kernel=False)[source]¶

Upgrade all packages, skip obsoletes if obsoletes=0 in yum.conf.

Exclude kernel upgrades by default.

fabtools.rpm.upgrade(kernel=False)[source]¶

Upgrade all packages, including obsoletes.

Exclude kernel upgrades by default.

fabtools.rpm.groupupdate(group, options=None)[source]¶

Update an existing software group, skip obsoletes if obsoletes=1 in yum.conf.

Extra options may be passed to yum if necessary.

fabtools.rpm.is_installed(pkg_name)[source]¶

Check if an RPM package is installed.

fabtools.rpm.install(packages, repos=None, yes=None, options=None)[source]¶

Install one or more RPM packages.

Extra repos may be passed to yum to enable extra repositories at install time.

Extra yes may be passed to yum to validate license if necessary.

Extra options may be passed to yum if necessary (e.g. ['--nogpgcheck', '--exclude=package']).

import fabtools

# Install a single package, in an alternative install root
fabtools.rpm.install('emacs', options='--installroot=/my/new/location')

# Install multiple packages silently
fabtools.rpm.install([
    'unzip',
    'nano'
], '--quiet')

fabtools.rpm.groupinstall(group, options=None)[source]¶

Install a group of packages.

You can use yum grouplist to get the list of groups.

Extra options may be passed to yum if necessary like (e.g. ['--nogpgcheck', '--exclude=package']).

import fabtools

# Install development packages
fabtools.rpm.groupinstall('Development tools')

fabtools.rpm.uninstall(packages, options=None)[source]¶

Remove one or more packages.

Extra options may be passed to yum if necessary.

fabtools.rpm.groupuninstall(group, options=None)[source]¶

Remove an existing software group.

Extra options may be passed to yum if necessary.

fabtools.rpm.repolist(status='', media=None)[source]¶

Get the list of yum repositories.

Returns enabled repositories by default. Extra status may be passed to list disabled repositories if necessary.

Media and debug repositories are kept disabled, except if you pass media.

import fabtools

# Install a package that may be included in disabled repositories
fabtools.rpm.install('vim', fabtools.rpm.repolist('disabled'))

System services¶

This module provides low-level tools for managing system services, using the service command. It supports both upstart services and traditional SysV-style /etc/init.d/ scripts.

fabtools.service.is_running(service)[source]¶

Check if a service is running.

import fabtools

if fabtools.service.is_running('foo'):
    print "Service foo is running!"

fabtools.service.start(service)[source]¶

Start a service.

import fabtools

# Start service if it is not running
if not fabtools.service.is_running('foo'):
    fabtools.service.start('foo')

fabtools.service.stop(service)[source]¶

Stop a service.

import fabtools

# Stop service if it is running
if fabtools.service.is_running('foo'):
    fabtools.service.stop('foo')

fabtools.service.restart(service)[source]¶

Restart a service.

import fabtools

# Start service, or restart it if it is already running
if fabtools.service.is_running('foo'):
    fabtools.service.restart('foo')
else:
    fabtools.service.start('foo')

fabtools.service.reload(service)[source]¶

Reload a service.

import fabtools

# Reload service
fabtools.service.reload('foo')

Warning

The service needs to support the reload operation.

fabtools.service.force_reload(service)[source]¶

Force reload a service.

import fabtools

# Force reload service
fabtools.service.force_reload('foo')

Warning

The service needs to support the force-reload operation.

Shorewall firewall¶

OpenSSH tasks¶

This module provides tools to manage OpenSSH server and client.

fabtools.ssh.harden(allow_root_login=False, allow_password_auth=False, sshd_config='/etc/ssh/sshd_config')[source]¶

Apply best practices for ssh security.

See fabtools.ssh.disable_password_auth() and fabtools.ssh.disable_root_login() for a detailed description.

import fabtools

# This will apply all hardening techniques.
fabtools.ssh.harden()

# Only apply some of the techniques.
fabtools.ssh.harden(allow_password_auth=True)

# Override the sshd_config file location.
fabtools.ssh.harden(sshd_config='/etc/sshd_config')

fabtools.ssh.disable_password_auth(sshd_config='/etc/ssh/sshd_config')[source]¶

Do not allow users to use passwords to login via ssh.

fabtools.ssh.enable_password_auth(sshd_config='/etc/ssh/sshd_config')[source]¶

Allow users to use passwords to login via ssh.

fabtools.ssh.disable_root_login(sshd_config='/etc/ssh/sshd_config')[source]¶

Do not allow root to login via ssh.

fabtools.ssh.enable_root_login(sshd_config='/etc/ssh/sshd_config')[source]¶

Allow root to login via ssh.

Supervisor processes¶

This module provides high-level tools for managing long-running processes using supervisord.

System settings¶

Systemd services¶

This module provides low-level tools for managing systemd services.

fabtools.systemd.enable(service)[source]¶

Enable a service.

fabtools.enable('httpd')

Note

This function is idempotent.

fabtools.systemd.disable(service)[source]¶

Disable a service.

fabtools.systemd.disable('httpd')

Note

This function is idempotent.

fabtools.systemd.is_running(service)[source]¶

Check if a service is running.

if fabtools.systemd.is_running('httpd'):
    print("Service httpd is running!")

fabtools.systemd.start(service)[source]¶

Start a service.

if not fabtools.systemd.is_running('httpd'):
    fabtools.systemd.start('httpd')

Note

This function is idempotent.

fabtools.systemd.stop(service)[source]¶

Stop a service.

if fabtools.systemd.is_running('foo'):
    fabtools.systemd.stop('foo')

Note

This function is idempotent.

fabtools.systemd.restart(service)[source]¶

Restart a service.

if fabtools.systemd.is_running('httpd'):
    fabtools.systemd.restart('httpd')
else:
    fabtools.systemd.start('httpd')

fabtools.systemd.reload(service)[source]¶

Reload a service.

fabtools.systemd.reload('foo')

Warning

The service needs to support the reload operation.

fabtools.systemd.start_and_enable(service)[source]¶

Start and enable a service (convenience function).

Note

This function is idempotent.

fabtools.systemd.stop_and_disable(service)[source]¶

Stop and disable a service (convenience function).

Note

This function is idempotent.

Users¶

fabtools.user.exists(name)[source]¶

Check if a user exists.

fabtools.user.create(name, comment=None, home=None, create_home=None, skeleton_dir=None, group=None, create_group=True, extra_groups=None, password=None, system=False, shell=None, uid=None, ssh_public_keys=None, non_unique=False)[source]¶

Create a new user and its home directory.

If create_home is None (the default), a home directory will be created for normal users, but not for system users. You can override the default behaviour by setting create_home to True or False.

If system is True, the user will be a system account. Its UID will be chosen in a specific range, and it will not have a home directory, unless you explicitely set create_home to True.

If shell is None, the user’s login shell will be the system’s default login shell (usually /bin/sh).

ssh_public_keys can be a (local) filename or a list of (local) filenames of public keys that should be added to the user’s SSH authorized keys (see fabtools.user.add_ssh_public_keys()).

Example:

import fabtools

if not fabtools.user.exists('alice'):
    fabtools.user.create('alice')

with cd('/home/alice'):
    # ...

fabtools.user.modify(name, comment=None, home=None, move_current_home=False, group=None, extra_groups=None, login_name=None, password=None, shell=None, uid=None, ssh_public_keys=None, non_unique=False)[source]¶

Modify an existing user.

ssh_public_keys can be a (local) filename or a list of (local) filenames of public keys that should be added to the user’s SSH authorized keys (see fabtools.user.add_ssh_public_keys()).

Example:

import fabtools

if fabtools.user.exists('alice'):
    fabtools.user.modify('alice', shell='/bin/sh')

fabtools.user.home_directory(name)[source]¶

Get the absolute path to the user’s home directory

Example:

import fabtools

home = fabtools.user.home_directory('alice')

fabtools.user.local_home_directory(name='')[source]¶

Get the absolute path to the local user’s home directory

Example:

import fabtools

local_home = fabtools.user.local_home_directory()

fabtools.user.authorized_keys(name)[source]¶

Get the list of authorized SSH public keys for the user

fabtools.user.add_ssh_public_key(name, filename)[source]¶

Add a public key to the user’s authorized SSH keys.

filename must be the local filename of a public key that should be added to the user’s SSH authorized keys.

Example:

import fabtools

fabtools.user.add_ssh_public_key('alice', '~/.ssh/id_rsa.pub')

fabtools.user.add_ssh_public_keys(name, filenames)[source]¶

Add multiple public keys to the user’s authorized SSH keys.

filenames must be a list of local filenames of public keys that should be added to the user’s SSH authorized keys.

Example:

import fabtools

fabtools.user.add_ssh_public_keys('alice', [
    '~/.ssh/id1_rsa.pub',
    '~/.ssh/id2_rsa.pub',
])

fabtools.user.add_host_keys(name, hostname)[source]¶

Add all public keys of a host to the user’s SSH known hosts file

Utilities¶

fabtools.utils.run_as_root(command, *args, **kwargs)[source]¶

Run a remote command as the root user.

When connecting as root to the remote system, this will use Fabric’s run function. In other cases, it will use sudo.

Tomcat¶

This module provides tools for installing Tomcat.

fabtools.tomcat.install_from_source(path='/usr/share/tomcat', version='7.0.47', mirror='http://archive.apache.org', overwrite=False)[source]¶

Install Tomcat from source.

import fabtools

# Install Tomcat
fabtools.tomcat.install_from_source(version='6.0.36')

fabtools.tomcat.start_tomcat()[source]¶

Start the Tomcat service.

fabtools.tomcat.stop_tomcat()[source]¶

Stop the Tomcat service.

fabtools.tomcat.version(path)[source]¶

Get the version of currently installed tomcat.

Returns None if it is not installed.

fabtools.tomcat.deploy_application(war_file, webapp_path=None)[source]¶

Deploy an application into the webapp path for a Tomcat installation.

Vagrant helpers¶

fabtools.vagrant.version()[source]¶

Get the Vagrant version.

fabtools.vagrant.ssh_config(name='')[source]¶

Get the SSH parameters for connecting to a vagrant VM.

fabtools.vagrant.vagrant[source]¶

Run the following tasks on a vagrant box.

First, you need to import this task in your fabfile.py:

from fabric.api import *
from fabtools.vagrant import vagrant

@task
def some_task():
    run('echo hello')

Then you can easily run tasks on your current Vagrant box:

$ fab vagrant some_task

fabtools.vagrant.vagrant_settings(name='', *args, **kwargs)[source]¶

Context manager that sets a vagrant VM as the remote host.

Use this context manager inside a task to run commands on your current Vagrant box:

from fabtools.vagrant import vagrant_settings

with vagrant_settings():
    run('hostname')

fabtools.vagrant.status(name='default')[source]¶

Get the status of a vagrant machine

fabtools.vagrant.machines()[source]¶

Get the list of vagrant machines

fabtools.vagrant.base_boxes()[source]¶

Get the list of vagrant base boxes

Apache¶

This module provides high-level tools for installing and configuring the Apache HTTP Server.

fabtools.require.apache.server()[source]¶

Require the Apache HTTP server to be installed and running.

from fabtools import require

require.apache.server()

fabtools.require.apache.module_enabled(module)[source]¶

Require an Apache module to be enabled.

This will cause Apache to reload its configuration.

from fabtools import require

require.apache.module_enabled('rewrite')

fabtools.require.apache.module_disabled(module)[source]¶

Require an Apache module to be disabled.

This will cause Apache to reload its configuration.

from fabtools import require

require.apache.module_disabled('rewrite')

fabtools.require.apache.site_enabled(config)[source]¶

Require an Apache site to be enabled.

This will cause Apache to reload its configuration.

from fabtools import require

require.apache.site_enabled('mysite')

fabtools.require.apache.site_disabled(config)[source]¶

Require an Apache site to be disabled.

This will cause Apache to reload its configuration.

from fabtools import require

require.apache.site_disabled('default')

fabtools.require.apache.site(site_name, template_contents=None, template_source=None, enabled=True, check_config=True, **kwargs)[source]¶

Require an Apache site.

You must provide a template for the site configuration, either as a string (template_contents) or as the path to a local template file (template_source).

from fabtools import require

CONFIG_TPL = '''
<VirtualHost *:%(port)s>
    ServerName %(hostname})s

    DocumentRoot %(document_root)s

    <Directory %(document_root)s>
        Options Indexes FollowSymLinks MultiViews

        AllowOverride All

        Order allow,deny
        allow from all
    </Directory>
</VirtualHost>
'''

require.apache.site(
    'example.com',
    template_contents=CONFIG_TPL,
    port=80,
    hostname='www.example.com',
    document_root='/var/www/mysite',
)

See also

fabtools.require.files.template_file()

Arch Linux packages¶

This module provides high-level tools for managing Arch Linux packages and repositories.

fabtools.require.arch.package(pkg_name, update=False)[source]¶

Require an Arch Linux package to be installed.

Example:

from fabtools import require

require.arch.package('foo')

fabtools.require.arch.packages(pkg_list, update=False)[source]¶

Require several Arch Linux packages to be installed.

Example:

from fabtools import require

require.arch.packages([
    'foo',
    'bar',
    'baz',
])

fabtools.require.arch.nopackage(pkg_name)[source]¶

Require an Arch Linux package to be uninstalled.

Example:

from fabtools import require

require.arch.nopackage('apache2')

fabtools.require.arch.nopackages(pkg_list)[source]¶

Require several Arch Linux packages to be uninstalled.

Example:

from fabtools import require

require.arch.nopackages([
    'perl',
    'php5',
    'ruby',
])

Curl¶

This module provides high-level tools for using curl.

fabtools.require.curl.command()[source]¶

Require the curl command-line tool.

Example:

from fabric.api import run
from fabtools import require

require.curl.command()
run('curl --help')

Debian packages¶

This module provides high-level tools for managing Debian/Ubuntu packages and repositories.

Files and directories¶

This module provides high-level tools for managing files and directories.

fabtools.require.files.directory(path, use_sudo=False, owner='', group='', mode='')[source]¶

Require a directory to exist.

from fabtools import require

require.directory('/tmp/mydir', owner='alice', use_sudo=True)

Note

This function can be accessed directly from the fabtools.require module for convenience.

fabtools.require.files.directories(path_list, use_sudo=False, owner='', group='', mode='')[source]¶

Require a list of directories to exist.

from fabtools import require
dirs=[
    '/tmp/mydir',
    '/tmp/mydear',
    '/tmp/my/dir'
]
require.directories(dirs, owner='alice', mode='750')

Note

This function can be accessed directly from the fabtools.require module for convenience.

fabtools.require.files.file(path=None, contents=None, source=None, url=None, md5=None, use_sudo=False, owner=None, group='', mode=None, verify_remote=True, temp_dir='/tmp')[source]¶

Require a file to exist and have specific contents and properties.

You can provide either:

• contents: the required contents of the file:

  from fabtools import require
  
  require.file('/tmp/hello.txt', contents='Hello, world')
  

• source: the local path of a file to upload:

  from fabtools import require
  
  require.file('/tmp/hello.txt', source='files/hello.txt')
  

• url: the URL of a file to download (path is then optional):

  from fabric.api import cd
  from fabtools import require
  
  with cd('tmp'):
      require.file(url='http://example.com/files/hello.txt')
  

If verify_remote is True (the default), then an MD5 comparison will be used to check whether the remote file is the same as the source. If this is False, the file will be assumed to be the same if it is present. This is useful for very large files, where generating an MD5 sum may take a while.

When providing either the contents or the source parameter, Fabric’s put function will be used to upload the file to the remote host. When use_sudo is True, the file will first be uploaded to a temporary directory, then moved to its final location. The default temporary directory is /tmp, but can be overridden with the temp_dir parameter. If temp_dir is an empty string, then the user’s home directory will be used.

If use_sudo is True, then the remote file will be owned by root, and its mode will reflect root’s default umask. The optional owner, group and mode parameters can be used to override these properties.

Note

This function can be accessed directly from the fabtools.require module for convenience.

fabtools.require.files.template_file(path=None, template_contents=None, template_source=None, context=None, **kwargs)[source]¶

Require a file whose contents is defined by a template.

fabtools.require.files.temporary_directory(template=None)[source]¶

Require a temporary directory.

The directory is created using the mktemp command. It will be created in /tmp, unless the TMPDIR environment variable is set to another location.

from fabtools.require.files import temporary_directory

tmp_dir = temporary_directory()

You can choose a specific location and name template for the temporary directory:

from fabtools.require.files import temporary_directory

tmp_dir = temporary_directory('/var/tmp/temp.XXXXXX')

You can also call this function as a context manager. In this case, the directory and its contents will be automatically deleted when exiting the block:

from pipes import quote
from posixpath import join

from fabtools.require.files import temporary_directory

with temporary_directory() as tmp_dir:
    path = join(tmp_dir, 'foo')
    run('touch %s' % quote(path))

Git¶

This module provides high-level tools for managing Git repositories.

fabtools.require.git.command()[source]¶

Require the git command-line tool.

Example:

from fabric.api import run
from fabtools import require

require.git.command()
run('git --help')

fabtools.require.git.working_copy(remote_url, path=None, branch='master', update=True, use_sudo=False, user=None)[source]¶

Require a working copy of the repository from the remote_url.

The path is optional, and defaults to the last segment of the remote repository URL, without its .git suffix.

If the path does not exist, this will clone the remote repository and check out the specified branch.

If the path exists and update is True, it will fetch changes from the remote repository, check out the specified branch, then merge the remote changes into the working copy.

If the path exists and update is False, it will only check out the specified branch, without fetching remote changesets.

Parameters:

remote_url (str) – URL of the remote repository (e.g. https://github.com/ronnix/fabtools.git). The given URL will be the origin remote of the working copy. path (str) – Absolute or relative path of the working copy on the filesystem. If this directory doesn’t exist yet, a new working copy is created through git clone. If the directory does exist and update == True, a git fetch is issued. If path is None the git clone is issued in the current working directory and the directory name of the working copy is created by git. branch (str) – Branch or tag to check out. If the given value is a tag name, update must be False or consecutive calls will fail. update (bool) – Whether or not to fetch and merge remote changesets. use_sudo (bool) – If True execute git with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

System groups¶

fabtools.require.groups.group(name, gid=None)[source]¶

Require a group.

from fabtools import require

require.group('mygroup')

Note

This function can be accessed directly from the fabtools.require module for convenience.

Mercurial¶

This module provides high-level tools for managing Mercurial repositories.

fabtools.require.mercurial.command()[source]¶

Require the hg command-line tool.

Example:

from fabric.api import run
from fabtools import require

require.mercurial.command()
run('hg --help')

fabtools.require.mercurial.working_copy(remote_url, path=None, branch='default', update=True, use_sudo=False, user=None)[source]¶

Require a working copy of the repository from the remote_url.

The path is optional, and defaults to the last segment of the remote repository URL.

If the path does not exist, this will clone the remote repository and check out the specified branch.

If the path exists and update is True, it will pull changes from the remote repository, check out the specified branch, then update the working copy.

If the path exists and update is False, it will only check out the specified branch, without pulling remote changesets.

Parameters:

remote_url (str) – URL of the remote repository path (str) – Absolute or relative path of the working copy on the filesystem. If this directory doesn’t exist yet, a new working copy is created through hg clone. If the directory does exist and update == True, a hg pull && hg up is issued. If path is None the hg clone is issued in the current working directory and the directory name of the working copy is created by hg. branch (str) – Branch or tag to check out. If the given value is a tag name, update must be False or consecutive calls will fail. update (bool) – Whether or not to pull and update remote changesets. use_sudo (bool) – If True execute hg with fabric.operations.sudo(), else with fabric.operations.run(). user (str) – If use_sudo is True, run fabric.operations.sudo() with the given user. If use_sudo is False this parameter has no effect.

MySQL¶

This module provides high-level tools for installing a MySQL server and creating MySQL users and databases.

fabtools.require.mysql.server(version=None, password=None)[source]¶

Require a MySQL server to be installed and running.

Example:

from fabtools import require

require.mysql.server(password='s3cr3t')

fabtools.require.mysql.user(name, password, **kwargs)[source]¶

Require a MySQL user.

Extra arguments will be passed to fabtools.mysql.create_user().

Example:

from fabric.api import settings
from fabtools import require

with settings(mysql_user='root', mysql_password='s3cr3t'):
    require.mysql.user('dbuser', 'somerandomstring')

fabtools.require.mysql.database(name, **kwargs)[source]¶

Require a MySQL database.

Extra arguments will be passed to fabtools.mysql.create_database().

Example:

from fabric.api import settings
from fabtools import require

with settings(mysql_user='root', mysql_password='s3cr3t'):
    require.mysql.database('myapp', owner='dbuser')